Advanced Square Terminal Features
Beta release
This is pre-release documentation for an API in public beta and is subject to change.
The Terminal API provides additional ways for a Square Terminal and a POS application to interact. These interactions are known as Terminal actions.
After pairing a Square Terminal with the Devices API, you can create a new CreateTerminalAction request, which is similar to requesting a checkout or refund. The POS application sends a request to Square using the Terminal API. The action request goes to Square, which then forwards it to the paired Square Terminal. The request carries the action and prompts the buyer with a screen based on the action type.
When the buyer completes the action on the Square Terminal, the POS application can be notified by a Square webhook or get the action result using the Terminal API.
The following example shows a POST request to create a new Terminal action for saving a card on file:
You can also retrieve a filtered list of Terminal action requests created by the account making the request by sending a POST request to the SearchTerminalActions endpoint. Terminal action requests are available for 30 days.
The following example shows a request to search for a Terminal action with the device status of PENDING
:
You can also send a POST request to cancel a Terminal action if the status of the request permits it or if the request is pending or in progress.
The following example shows a POST request to cancel a Terminal action that takes an action_id
in the path parameter:
The Terminal API provides the following Terminal actions:
The
SAVE_CARD
action type saves the customer card on file for future transactions. For more information, see Save a Card on File with the Terminal API.The
PING
action type checks whether the specific Square Terminal device is online or currently active with the seller. For more information, see Check Device Information for a Square Terminal.The
RECEIPT
action type launches the receipt option screen on the Square Terminal, where the buyer can choose how to receive a receipt for a given transaction. For more information, see Print or Issue Receipts for Cash Payments and Previous Transactions.
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.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.