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.
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.
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.
Create a
PING
Terminal action request using the CreateTerminalAction endpoint that includes thePING
action type and thedevice_id
, which is found on the back of the Square Terminal device.You receive a
TerminalAction
response that includes an ID and aPENDING
action status.
After the Terminal device has acknowledged the request, the action status transitions from a
PENDING
state to aCOMPLETED
state and the action object updates with the device's details indevice_metadata
.
Using the
action.id
fromCreateActionResponse
, create a GET request using the GetTerminalAction endpoint to retrieve thePING
action.The
PING
Terminal action is in aPENDING
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 theterminal.action.created
andterminal.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.
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
.
If you need more assistance, contact Developer Support or ask for help in the Developer Forums.