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.

Link to section

Create a Terminal action request

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:

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": "SAVE_CARD",
      "save_card_options": {
        "customer_id": "{{CUSTOMER_ID}}",
        "reference_id": "user-id-1"
      }
    }
  }'

Link to section

Search for a Terminal action request

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:

curl https://connect.squareup.com/v2/terminals/actions/search \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": {
      "filter": {
        "status": "PENDING"
      }
    }
  }'

Link to section

Cancel a Terminal action request

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:

curl https://connect.squareup.com/v2/terminals/actions/{action_id}/cancel \
  -X POST \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

Link to section

Types of Terminal actions

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.

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.