Customize Screen Interactions for Non-Payment Workflows

Applies to: Terminal API

Learn how to customize how buyers interact with the Square Terminal through screen workflows.

Link to section


In addition to processing checkouts and refunds, the Terminal API allows you to configure buyer-facing screen interactions for the Square Terminal and build non-payment-related workflows that collect buyer information. You can configure these custom screen workflows using Terminal actions.

Link to section

Requirements and limitations

  • 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.
Link to section

Display screens with Terminal actions

With the CreateTerminalAction endpoint, you can send action requests that trigger the Square Terminal to display a screen. In the request, you can customize the screen text and how the buyer provides their information on the screen's input fields.

In a Terminal action request, you specify the action type in the request body for a given screen. The Terminal API provides the following Terminal action types:

  • Confirmation screen - Allows you to collect a buyer's confirmation decision to the terms displayed on the screen.
  • Signature capture - Allows you to capture a buyer's signature for their records.
  • Data collection - Allows you to collect contact information from the buyer, such as a phone number and email address.
  • Menu select - Allows you to display a list of options for the buyer to select.
  • QR code display - Allows you to display a QR code for buyers to scan.


After 30 days, Square deletes any buyer data that you captured from custom workflows and are returned from completed actions. If required, you must store the buyer data within the 30-day period.

Link to section

Next steps

Choose a type of buyer screen engagement to set up for the Square Terminal:

You can also link multiple screens to display in sequence for a given screen workflow and dismiss actions. For more information, see Link and Dismiss Terminal Actions.