Use the Square Terminal to customize buyer workflows, save cards on file, check a device status, and perform other tasks.
Terminal API

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:

Create Terminal Action
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
  • 14
  • 15
  • 16
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"
      }
    }
  }'

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:

Search Terminal Actions
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
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"
      }
    }
  }'

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:

Cancel Terminal Action
  • 1
  • 2
  • 3
  • 4
  • 5
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'

The Terminal API provides the following Terminal actions:

  • 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.

We've made improvements to our docs.
Prefer the old format?