Terminal API

Check Device Information for a Square Terminal Beta release

This is pre-release documentation for an API in public beta and is subject to change.

After pairing a Square Terminal and a POS application, use the Terminal API to check the real-time device information of one or more remote devices. This feature uses the Terminal action endpoint and the PING Terminal action type. When you need to remotely monitor the performance of a group of Square Terminal devices, use the PING Terminal action to capture information such as network connectivity, battery level, and device OS version.

Link to section
When to check for device information

You might need to check the device information when:

A seller has a group of devices that are not operated by anyone on the floor (automated operation).
You are not located at the same customer site as the seller (remote monitoring).
You need to regularly monitor network connections due to a recent server outage.

The Terminal actions endpoint provides a foundational method for using the Terminal API to collect device information in real time and measure device availability. With the PING Terminal action, you send a request to the device and see whether a device is connected to your seller's network, as indicated by the device's status. If the device is online and sends a response back, you can get additional device status updates.

As a device monitoring and health status feature, you can periodically use the PING Terminal action so that your seller's devices maintain availability for buyers. The Terminal action request and response are limited to devices that are signed in with a Terminal API device code and that are paired with the Terminal API and your POS application.

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.

Link to section
Set up the PING Terminal action

Create a PING Terminal action request using the CreateTerminalAction endpoint that includes the PING action type and the device_id, which is found on the back of the Square Terminal device.

Create Terminal Action

1
2
3
4
5
6
7
8
9
10
11
12

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": "PING"
    }
  }'

You receive a TerminalAction response that includes an ID and a PENDING action status.

1
2
3
4
5
6
7
8
9
10
11
12
13

{
   "action": {
      "id": "termapia:vguubuhbiuhfyrfrugv",
      "device_id": "device_id123",
      "deadline_duration": "PT5M",
      "status": "PENDING",
      "created_at": "2021-07-28T23:22:07.476Z",
      "updated_at": "2021-07-28T23:22:07.476Z",
      "location_id": "LWTMJESMBQXZC9",
      "type": "PING",
      "app_id": "sq0ids-ESXCwyTF7NBxodprF_pvhA"
   }
}

After the Terminal device has acknowledged the request, the action status transitions from a PENDING state to a COMPLETED state and the action object updates with the device's details in device_metadata.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

{
   "action": {
       "id": "termapia:vguubuhbiuhfyrfrugv",
       "device_id": "deviceId123",
       "deadline_duration": "PT5M",
       "status": "COMPLETED",
       "created_at": "2021-07-28T23:22:07.476Z",
       "updated_at": "2021-07-28T23:22:07.476Z",
       "location_id": "LWTMJESMBQXZC9",
       "type": "PING",
       "app_id": "sq0ids-ESXCwyTF7NBxgzdrF_pvhA",
       "device_metadata": {
          "os_version": "5.1.0025",
          "app_version": "5.91",
          "serial_number": "107CS13101339420",
          "payment_region": "US",
          "network_connection_type": "WIFI",
          "wifi_network_name": "MyNetwork",
          "wifi_network_strength": "GOOD",
          "ip_address": "192.158.1.38",
          "battery_percentage": "80",
          "charging_state": "NOT_CHARGING",
          "location_id": "locationid123",
          "merchant_id": "merchantId123"
       }
   }
}

Using the action.id from CreateActionResponse, create a GET request using the GetTerminalAction endpoint to retrieve the PING action.
Get Terminal Action
- 1
- 2
- 3
- 4
```
curl https://connect.squareup.com/v2/terminals/actions/{action_id} \
  -H 'Square-Version: 2023-05-17' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'
```
Try in API Explorer
The PING Terminal action is in a PENDING state if the Square Terminal has not acknowledged the request, it is dealing with a slow Internet connection, it is turned off, or it is not signed in to the Terminal API application using a device code from the Devices API. In this case, subscribe to the terminal.action.created and terminal.action.updated webhooks. For more information, see Square Webhooks Overview.

Link to section
Search for a PING Terminal action by status

You can also search for devices based on a specified status. When you send the POST request to the SearchTerminalActions endpoint, provide the status query in the request body. You can query by specifying PENDING, IN-PROGRESS, COMPLETED, or CANCELED for the status. The following request example specifies the PING action type and a limit of 2 for the amount of results returned from the request:

Search Terminal Actions

1
2
3
4
5
6
7
8
9
10
11
12
13
14

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": {
      "type": "PING",
      "filter": {
        "status": "CANCELED"
      }
    },
    "limit": 2
  }'

The response returns the device status and device information, as well as information about the action object.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
   "action": [
    {
       "id": "termapia:sdmfsdkmflsgmlsk",
       "device_id": "device123",
       "deadline_duration": "PT5M",
       "status": "CANCELED",
       "cancel_reason": "TIMED_OUT",
       "created_at": "2021-08-03T16:52:58.082Z",
       "updated_at": "2021-08-03T16:57:58.699Z",
       "location_id": "locationId123",
       "type": "PING",
       "app_id": "sq0ids-ESXCwyTF7NBxgzdrF_pvhA",
     },
    {
       "id": "termapia:sdfdsgsdgsdsfa",
       "device_id": "device123",
       "deadline_duration": "PT5M",
       "status": "CANCELED",
       "cancel_reason": "TIMED_OUT",
       "created_at": "2021-08-03T16:52:58.082Z",
       "updated_at": "2021-08-03T16:57:58.699Z",
       "location_id": "locationId123",
       "type": "PING",
       "app_id": "sq0ids-ESXCwyTF7NBxgzdrF_pvhA",
   },
 ]
}

Link to section
Subscribe to events for Terminal action status updates

When a Terminal action object is created or updated, webhook notifications are sent to the endpoint that is registered for a POS application. To get the notifications, be sure that your application is updated in the Developer Dashboard with the following webhooks:

terminal.action.created
terminal.action.updated

A full copy of the object is sent to your application at your webhook URL for every action status update, which includes PENDING, IN_PROGRESS, COMPLETED, or CANCELED.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

{
  "merchant_id": "ABCXJLNDS6BE",
  "type": "terminal.action.updated",
  "event_id": "12345678-e125-4998-83eb-170a6e29433b",
  "created_at": "2022-06-08T13:57:31.372Z",
  "data": {
    "type": "action.event",
    "id": "termapia:abcd12349UOukCE",
    "object": {
      "action": {
        "app_id": "sq0idp-abc1234_RWKfWkLesEPp8g",
        "created_at": "2022-06-08T13:57:29.976Z",
        "deadline_duration": "PT5M",
        "device_id": "0000000000000000",
        "device_metadata": {
          "app_version": "5.92",
          "battery_percentage": "44",
          "charging_state": "CHARGING",
          "ip_address": "0.0.0.0",
          "location_id": "L5XXSEKV2GFMB",
          "merchant_id": "ABCXJLNDS6BE",
          "network_connection_type": "WIFI",
          "os_version": "5.19.0048",
          "payment_region": "US",
          "serial_number": "0000000000000000",
          "wifi_network_name": "Block Wifi",
          "wifi_network_strength": "EXCELLENT"
        },
        "id": "termapia:12345iXIdUOAkCE",
        "status": "COMPLETED",
        "type": "PING",
        "updated_at": "2022-06-08T13:57:31.372Z"
      }
    }
  }
}

If you need more assistance, contact Developer Support or ask for help in the Developer Forums.

Docs

Check Device Information for a Square Terminal Beta release

This is pre-release documentation for an API in public beta and is subject to change.

Link to section
When to check for device information

Link to section
Prerequisites

Link to section
Set up the PING Terminal action

Link to section
Search for a PING Terminal action by status

Link to section
Subscribe to events for Terminal action status updates

On this page

Docs

Check Device Information for a Square Terminal Beta release This is pre-release documentation for an API in public beta and is subject to change.

Link to section When to check for device information

Link to section Prerequisites

Link to section Set up the PING Terminal action

Link to section Search for a PING Terminal action by status

Link to section Subscribe to events for Terminal action status updates

On this page

Check Device Information for a Square Terminal Beta release

This is pre-release documentation for an API in public beta and is subject to change.

Link to section
When to check for device information

Link to section
Prerequisites

Link to section
Set up the PING Terminal action

Link to section
Search for a PING Terminal action by status

Link to section
Subscribe to events for Terminal action status updates