Integrate the POS application at the seller's location by pairing it with a Square Terminal.
Terminal API

POS Application Integration with the Terminal API

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 CreateDeviceCode endpoint to send the request:

Create Device Code
  • 1
  • 2
  • 3
  • 4
  • 5
  • 6
  • 7
  • 8
  • 9
  • 10
  • 11
  • 12
  • 13
curl https://connect.squareup.com/v2/devices/codes \
  -X POST \
  -H 'Square-Version: 2022-11-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "4bffb735-5ea9-45b4-889a-d33200b12ad2",
    "device_code": {
      "name": "Counter 1",
      "product_type": "TERMINAL_API",
      "location_id": "NHTLE2589dCGJ"
    }
  }'

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.

The following response example shows the generated unique ID of the Square Terminal:

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 Seller Dashboard by choosing Accounts & Settings, and then choosing Devices.

Whether accessed through the Devices API or the Seller Dashboard, the DeviceCode object represents whether the device code has been used to sign in to a Terminal device. It does not represent the current status of the device.

To get started with pairing a POS application to a Square Terminal, see Connect a Square Terminal.

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