Terminal API

Print or Issue Receipts for Cash Payments and Previous Transactions Beta release

This is pre-release documentation for an API in public beta and is subject to change.

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 the Terminal action endpoints, such as CreateTerminalAction, and the RECEIPT Terminal action type.

Link to section
When to issue receipts

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.

Link to section
Prerequisites

A Square Terminal 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 the Square Terminal FAQ.
Your developer account must be enabled to subscribe to Terminal API action webhooks.

Link to section
Display the receipt options screen

Specify RECEIPT as the action type in a new CreateTerminalAction request.
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
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
```
curl https://connect.squareup.com/v2/terminals/actions \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "5f2e1vb9-c86a-6431-88d2-c0b49a84df66",
    "action": {
      "device_id": "{DEVICE_ID}",
      "type": "RECEIPT",
      "receipt_options": {
        "payment_id": "Bg049luXa4AtNdLLxDStc1c6GKSZY"
      }
    }
  }'
```
Try in API Explorer
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.
- 1
- 2
- 3
- 4
- 5
- 6
- 7
- 8
- 9
- 10
- 11
- 12
- 13
- 14
- 15
```
{
 "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.
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.

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Print or Issue Receipts for Cash Payments and Previous Transactions Beta release

This is pre-release documentation for an API in public beta and is subject to change.

Link to section
When to issue receipts

Link to section
Prerequisites

Link to section
Display the receipt options screen

On this page

Docs

Print or Issue Receipts for Cash Payments and Previous Transactions Beta release This is pre-release documentation for an API in public beta and is subject to change.

Link to section When to issue receipts

Link to section Prerequisites

Link to section Display the receipt options screen

On this page

Print or Issue Receipts for Cash Payments and Previous Transactions Beta release

This is pre-release documentation for an API in public beta and is subject to change.

Link to section
When to issue receipts

Link to section
Prerequisites

Link to section
Display the receipt options screen