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.
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 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.
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 theRECEIPT
type and apayment_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 tofalse
.print_only
. Instructs the device to print the receipt without displaying the receipt selection screen. Defaults tofalse
. If the seller prefers for the Square Terminal to directly print receipts without presenting the buyer with the receipt options screen, set theprint_only
parameter totrue
.
A Terminal action accepts a
payment_id
and prompts the Square Terminal to present a screen that displays receipt options to the buyer.You receive a
TerminalAction
response that includes an ID and aPENDING
action status, which means the Square Terminal has yet to receive the Terminal receipt action request.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.