Print or Issue Receipts for Cash Payments and Previous Transactions

Applies to: Terminal API | Devices API | Payments API

Learn how to use the Square Terminal and a POS application to print or issue receipts for cash payments and previous transactions.

After pairing a Square Terminal using the Devices API, use the Terminal API to print or issue a receipt for a pre-existing payment or for a cash payment after recording it with the Payments API. This feature uses Terminal action endpoints (such as CreateTerminalAction) and the RECEIPT Terminal action type.

With the RECEIPT action type, the Terminal API supports workflows where a seller can print a receipt at the buyer's request. In previous releases, the only way a seller could print a receipt is immediately after a checkout.

The seller can print or issue a receipt in the following situations:

• A buyer comes back to the seller and requests a reprint of a receipt.
• A purchase is made in cash and the buyer requests a receipt for the purchase.
• A buyer wants to receive a digital receipt by email or text message (SMS) or receive a printed receipt.

• A Square Terminal must be paired with a POS application.
• Applications must have the following OAuth permissions:
  • PAYMENTS_READ for getting or searching for a Terminal action request.
  • PAYMENTS_WRITE for creating or canceling a Terminal action request.
• Ensure that the Square Terminal software is up to date. On the Square Terminal, choose Settings, choose General, choose About Terminal, and then check the software version. For more information, see Square Terminal FAQ.
• Your developer account must be enabled to subscribe to Terminal API action webhooks.

1. Specify RECEIPT as the action type in a new CreateTerminalAction request.

2. Specify a configuration for the receipt action in the receipt_option property. This requires the RECEIPT type and a payment_id. You can add either of the following Boolean configurations or add all the configurations to the request:

   • is_duplicate - Identifies the receipt as a reprint rather than an original receipt. Defaults to false.
   • print_only - Instructs the device to print the receipt without displaying the receipt selection screen. Defaults to false. If the seller prefers for the Square Terminal to directly print receipts without presenting the buyer with the receipt options screen, set the print_only parameter to true.

   A Terminal action accepts a payment_id and prompts the Square Terminal to present a screen that displays receipt options to the buyer.

   Create terminal action

   cURL

   You receive a TerminalAction response that includes an ID and a PENDING action status, which means the Square Terminal has yet to receive the Terminal receipt action request.

   {
     "action": {
        "id": "termapia:HLSMg7K7lyawJiCE",
        "device_id": "{{DEVICE_ID}}",
        "deadline_duration": "PT5M",
        "status": "PENDING",
        "created_at": "2021-12-27T23:42:43.647Z",
        "updated_at": "2021-12-27T23:42:43.647Z",
        "type": "RECEIPT",
        "app_id": "sq0ids-scQ0-9iAmZkSGnbVvHPWXw",
        “receipt_options”: {
           “payment_id”: “Bg049luXa4AtNdLLxDStc1c6GKSZY”
        }
     }
   }

   After the Square Terminal receives the Terminal receipt action request, the Square Terminal displays the receipt option screen. Depending on which configurations options you provided in the request, the receipt option screen prompts the buyer to choose how to receive the receipt.

3. After the Square Terminal completes printing or issuing a receipt, the Square Terminal returns to the idle screen and the Terminal receipt action transitions to the COMPLETED status.