Manage Terminal Actions Beta release

Applies to: Terminal APITerminal API

Learn how to customize buyer workflows, save cards on file, check a device status, and perform other tasks.

The Terminal APITerminal API provides additional ways for a Square Terminal and a Point of Sale (POS) application to interact. These interactions are called Terminal actions.

• 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 FAQSquare Terminal FAQ.
• Your developer account must be enabled to subscribe to Terminal API action webhooksTerminal API action webhooks.

After pairing a Square Terminal using the Devices API, you can create a new CreateTerminalActionCreateTerminalAction 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 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 retrieve a filtered list of Terminal action requests created by an account by sending a POST request to the SearchTerminalActionsSearchTerminalActions 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 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 allows you to create the following Terminal actions:

• Save a card on file - This action saves the customer card on file for future transactions. For more information, see Save a Card on File with the Terminal APISave a Card on File with the Terminal API.
• Check device information - This action checks whether the specific Square Terminal is online or active with the seller. For more information, see Check Device Information for a Square TerminalCheck Device Information for a Square Terminal.
• Print or issue a receipt - This action 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 TransactionsPrint or Issue Receipts for Cash Payments and Previous Transactions.
• Custom screen workflow - This action launches buyer-facing screen interactions, which allow you to build non-payment-related workflows that capture buyer information on the Square Terminal. You can configure these custom screen workflows to extend buyer engagements for the seller's business. For more information, see Customize Screen Interactions for Non-Payment WorkflowsCustomize Screen Interactions for Non-Payment Workflows.

In addition to Terminal actions, the Terminal API allows sellers to customize the Square Terminal idle screen and showcase their business and brand. For more information, see Customize the Square Terminal Idle ScreenCustomize the Square Terminal Idle Screen.