Check Device Information for a Square Terminal

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.

You might need to check the device information when:

• A seller has a group of devices that aren't operated by anyone on the floor (automated operation).
• You're 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.

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

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

   cURL

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

   {
      "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"
      }
   }

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

   {
      "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"
          }
      }
   }

3. Using the action.id from CreateActionResponse, create a GET request using the GetTerminalAction endpoint to retrieve the PING action.

   Get terminal action

   cURL

   The PING Terminal action is in a PENDING state if the Square Terminal hasn't acknowledged the request, it's dealing with a slow Internet connection, it's turned off, or it's 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.

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:

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

{
   "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",
   },
 ]
}

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.

{
  "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"
      }
    }
  }
}