Applies to: Terminal API | Devices API
Learn how the Square Terminal and a POS application operate together as a paired system.
Integrating a Point of Sale (POS) application with the Terminal API requires using the Devices API to pair the POS application with the Square Terminal using a device code and connecting the Square Terminal to Square for processing payments.
A POS application cannot be physically connected to a Square Terminal but must be paired using the Devices API and a wireless Internet connection before a checkout can be processed.
The Devices API pairs a POS application with a Square Terminal as long as the Square Terminal is wirelessly connected to Square. The Devices API lets the application request a pairing and returns a device code for the seller to use. The request is sent to Square, which then directly connects to the Square Terminal using the wireless connection. When the connection is made, Square sends the device code back to the application.
The following request example uses the Devices API CreateDeviceCode endpoint to send the request:
Create device code
To obtain the device code, you need the DEVICE_CREDENTIAL_MANAGEMENT OAuth permission enabled so that you can use the Devices API to connect to the Square Terminal.
The seller uses the device code to sign in to a Square Terminal. After the seller signs in, the Devices API returns the unique ID of the Square Terminal as a DeviceCode.device_id. The ID is used in later Terminal checkout requests.
Important
The Square Dashboard also generates device codes; however, they won't work for successfully pairing to a Square Terminal. Make sure that you use the device code that the Devices API generated and not the device code from the Square Dashboard.
The following response example shows the generated unique ID of the Square Terminal:
{
"device_code": {
"id": "AF7AJW6VM31P3",
"name": "Terminal API Device created on Sep 14, 2022",
"code": "JHHYHH",
"product_type": "TERMINAL_API",
"location_id": "NHTLE2589dCGJ",
"pair_by": "2022-09-15T00:01:18.000Z",
"created_at": "2022-09-14T23:56:18.000Z",
"status": "UNPAIRED",
"status_changed_at": "2022-09-14T23:56:18.000Z"
}
}The Devices API DeviceCode object represents a POS application/Square Terminal pairing. It contains the sign-in code, pairing status, and device ID of the Square Terminal.
When the Square Terminal is paired, the application can send checkout requests using the Terminal API. The Square Terminal uses the wireless connection with Square to get payment information from the request and collect the payment from the buyer.
Note
You can see the device pairing state in the Square Dashboard by choosing Accounts & Settings, and then choosing Devices.
Whether accessed through the Devices API or the Square Dashboard, the DeviceCode object represents whether the device code has been used to sign in to a Terminal device. It doesn't represent the current status of the device.
For a complete list of Devices API OAuth permissions to configure the Square Terminal, see OAuth Permissions Reference.
To get started with pairing a POS application to a Square Terminal, see Connect a Square Terminal to a POS Application.