Learn how to integrate a custom POS application with a Square Terminal to take payments through a Terminal checkout.
Terminal API

Connect a Square Terminal

Use the Devices API to connect a Square Terminal to a point-of-sale (POS) application.

Overview Permalink Get a link to this section

This topic walks you through the development steps necessary to connect a third-party POS application to a Square Terminal. At a high level, you learn about:

  • OAuth permissions needed to call the Terminal API and Devices API.

  • Pairing, signing in, and signing out a Square Terminal.

After you have completed the integration steps in this topic, see Take Payments with the Terminal API to learn about taking a payment with the Terminal API.

Did you know?

The Square Sandbox does not support the Devices API. If you are testing a Terminal API application in the Sandbox, use a Sandbox device ID that simulates a Square Terminal from the list of Sandbox test values for the Terminal API instead of production device IDs obtained with the Devices API.

Register your POS application and set up webhooks Permalink Get a link to this section

Before you can integrate a Square Terminal and the Devices API, you need to complete the following tasks:

The application registration allows you to get the access tokens you need to call Square APIs. If you use OAuth tokens, use the Developer Dashboard to test your OAuth flow in the Square Sandbox.

Square sends webhook notifications with each status update for a Square Terminal pairing request and for a Terminal API checkout request status update. If you add listening endpoints for these webhook notifications, you avoid polling a Square server to get the current status of either request. The application webhook endpoint should listen for the following notifications:

  • device.code.paired. Notifies of a pairing completion.

  • terminal.checkout.created. Acknowledges a new Terminal checkout.

  • terminal.checkout.updated. Notifies of a checkout status change.

The webhook payload for device.code.paired is an instance of DeviceCode with the current state of the object.

The webhook payload for the terminal.checkout notifications is an instance of the TerminalCheckout whose properties have changed as the connected Square Terminal processes the checkout.

Learn about OAuth permissions for a Square Terminal Permalink Get a link to this section

When setting up your OAuth flow, request the minimum permissions necessary to pair a Square Terminal and request a checkout. Doing so might increase adoption of your application and reduce your liability.

The following are the minimum permissions you need to request:





When sellers sign in to an integrated POS application, they should be redirected to a URL as shown in the following example:

The Square authorization page asks sellers to accept the POS application request for access to their Square Terminal credential cache, access to their seller profile, and read/write access to payments in their Square account.


If you are building an application for accounts other than your own, use the OAuth API to generate tokens for each of your customers. Each customer creates and uses their own device codes to put their Terminal into Connected Mode.

Set up a Square Terminal device Permalink Get a link to this section

A new Square Terminal must be set up before use. If a previously setup device is powered off, after turning it on, check for software updates that might have been missed while the Terminal was powered off.

  1. Power on the Square Terminal and connect it to your Wi-Fi network.

  2. On the Terminal Sign in Page, choose Change Settings, choose General, and then choose About Terminal. If there are any pending software updates, update the Square Terminal to the latest version.

Sign in to a Square Terminal Permalink Get a link to this section

When a device code is available for the requested Square Terminal, a seller signs in to the Square Terminal using the following steps:

  1. On the Sign in Page, choose the Device Code button.

  2. Request a new device code by sending a POST request to v2/devices/codes.

  3. Display this code to the person performing the setup.

  4. Use the device code your application gathered.

    The Terminal screen should look like the following:

    A graphic showing a Square Terminal Ready screen.

Sign out of a Square Terminal paired mode Permalink Get a link to this section

If your Square Terminal is paired with a POS client, you might want to sign out of the Terminal. This lets you pair the Square Terminal with a different POS client or use the Square Point of Sale application.

  1. Swipe from the left side of the screen to open the navigation drawer.

  2. Choose Settings.

  3. Choose Sign Out at the bottom of the menu.

Pair a POS client with a Square Terminal Permalink Get a link to this section

If you have not set up your Square Terminal for testing code in development, you should complete the setup before proceeding with this topic.

A seller might have more than one location where Square Terminals are used. In this case, when pairing a Square Terminal, the seller should pick the location of the Square Terminal to be paired. Otherwise, the default seller location is used. Before a POS application can use a Square Terminal to check out a buyer, the POS must be paired to a Square Terminal at either the chosen location or the default location.


The Terminal API can only be used with device codes returned by the CreateDeviceCode endpoint. Other device codes, such as those created in the Seller Dashboard, are not compatible with the Terminal API.

The pairing process follows these steps:

  1. (Optional) The POS client uses the Locations API to present a location picker for the seller. If a location ID is not set in the request, the default location is used.

  2. The POS client gets a device code by providing friendly name and an optional location ID.

  3. The seller enters the device code into the Square Terminal to sign in.

  4. The Square Terminal notifies Square that it is signed in using the device code.

  5. The POS and Square Terminal are paired when the device code has been used to sign in to the Terminal.

  6. The POS client receives a webhook that shows pairing is enabled and provides a device ID to be used in checkout requests for the paired Terminal.

Request a device code Permalink Get a link to this section

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-06-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json' \
  -d '{
    "idempotency_key": "123-456-789",
    "device_code": {
      "name": "Counter 1",
      "product_type": "TERMINAL_API",
      "location_id": "NHT...CGJ"

The response returns several fields, including:

  • The friendly name you used in the request.

  • The device pairing status, which is currently UNPAIRED.

  • The device code to enter into the Square Terminal.

  • The date and time on which the device code expires if not used.


If a location ID is not set in the request, the response location_id value is the default location for the seller.

After a device code is created, it must be used to sign in to a Square Terminal within 5 minutes. If the device code is not used within 5 minutes, it expires and a new device code must be requested. After the initial sign-in, the device code can be used to sign in to the same Square Terminal in the future.

After a seller signs in to a Square Terminal with the code, the status changes to PAIRED and the device_id value of the Terminal device is available. The device ID is the serial number on the underside of the Square Terminal.

A seller can now sign in to a Square Terminal using the device code. When signed in, the POS client is notified as described in the following sections.

Listen for the device pairing webhook (optional) Permalink Get a link to this section

Validate the webhook notification for device.code.paired.

The following example shows the payload of the webhook:

Request the pairing status (optional) Permalink Get a link to this section

The Devices API returns the current status of a device pairing with a GET command, as shown in the following example:

Get Device Code
  • 1
  • 2
  • 3
  • 4
curl https://connect.squareup.com/v2/devices/codes/DEVICE_CODE_ID \
  -H 'Square-Version: 2022-06-16' \
  -H 'Authorization: Bearer ACCESS_TOKEN' \
  -H 'Content-Type: application/json'

If the device code has not expired, a response like the following example is returned:

Check the status of the device code. If it is not PAIRED, you need to request the device pairing again. Keep checking until the device is PAIRED. When paired, the POS client can send Terminal checkout requests.


Expired device codes are not returned in the ListDeviceCodes and GetDeviceCode operations.

Requirements and limitations Permalink Get a link to this section

  • Applications must have the following OAuth permission: DEVICE_CREDENTIAL_MANAGEMENT to get a device code.

  • You cannot take cash payments with the Terminal API.

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