Learn how Square Terminal checkouts and the Terminal and Devices APIs enable integrating a POS application with the Square Terminal.
Terminal API

Square Terminal Integration Overview

Use the Devices API to pair a custom point-of-sale (POS) application with a Square Terminal and the Terminal API to take in-person payments with payment cards on the paired Terminal.

Overview Permalink Get a link to this section

The Terminal API and Devices API let developers integrate Square in-person payments in all supported areas and Canadian Interac refunds in custom POS applications using a Square Terminal that supports authorization and payment processing. The Square Terminal simplifies chip and NFC payments, addresses EMV certification requirements, and makes PCI compliance easy.

A graphic showing a Square Terminal device.


The Terminal API is available in Australia, Canada, France, Ireland, Japan, Spain, the United Kingdom, and the United States.

If you are taking payments with an Android or iOS device and a Square Reader, you must use the Reader SDK to integrate payments in your application.

Pair a Terminal with the Devices API Permalink Get a link to this section

A POS client cannot be physically connected to a Square Terminal but must be paired using the API and a wireless Internet connection before a checkout can be processed.

The Devices API can pair a POS client with a Square Terminal as long as the Terminal is wirelessly connected to Square. The API lets the POS 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 Terminal using the wireless connection. When the connection is made, Square sends the device code back to the POS.

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 Terminal as a DeviceCode.device_id. The ID is used in later Terminal checkout requests. The Devices API DeviceCode object represents a POS client/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 POS client 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.


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.

Check out with Square Terminal Permalink Get a link to this section

A POS application sends a request to check out a buyer on a paired Square Terminal by using the Terminal API. The Terminal checkout request goes to Square, which forwards it to the paired Square Terminal. The request carries the total amount to collect and the expected Square Terminal payment screen behavior.

Use a Terminal API checkout request to set Square Terminal behavior per checkout request. Customizable behaviors include:

  • Skipping the receipt screen.

  • Showing a separate tip input screen before getting a buyer's signature.

  • Allowing custom tip amounts.

  • Skipping the signature screen.

The Terminal API lets a POS client set payment completion options per checkout.

When the buyer completes the checkout on the Square Terminal, the POS application can be notified by a Square webhook. If the POS application is not listening for webhook notifications, it can get the checkout result using the Terminal API.

A POS application can get a history of checkout requests and results filtered by Terminal device ID, time range, and checkout status.


Checkouts in either the COMPLETED or CANCELED state are DELETED after 30 days. The Payment object serves as your permanent record.

Payment types Permalink Get a link to this section

The Terminal API supports payment cards and NFC payments such as Apple Pay and Google Pay. Payment cards include Square gift cards, credit cards, debit cards, and prepaid debit cards. In Japan, E-money card payments are also accepted. The Square Terminal does not support cash payments.

To learn more, see Supported Payment Cards by Country.

Did you know?

The Terminal API does not support payments split across multiple payment cards. If multiple payments are needed, you can create a checkout for each partial payment.

Refund Square Terminal Interac payments Permalink Get a link to this section

For Canadian sellers who want to refund payments on Interact cards, use the Terminal API to request an in-person refund on a Square Terminal. To learn more, see Refund Interac Payments.

Did you know?

Refunds for most Terminal payments use the Refunds API. Terminal API refunds should only be used when the payment card requires it. The payment record might include a true value in the refund_requires_card_presence field to identify when the Terminal API refund is to be used.

Terminal actions Permalink Get a link to this section

The Terminal API provides additional ways for a Square Terminal and your POS application to interact. These interactions are known as Terminal actions.


Terminal actions are currently in beta.

After pairing a Square Terminal with the Devices API, you can create a new Terminal action, which is similar to requesting a checkout or refund. The POS application sends a request to Square by using the Terminal API. The action request goes to Square, which then forwards it to the paired Square Terminal. The request carries the action and prompts the buyer with a screen based on the action type.

When the buyer completes the action on the Square Terminal, the POS application can be notified by a Square webhook or get the action result using the Terminal API.

The following describes two Terminal actions that provide additional Square Terminal capabilities:

Listen for Terminal API webhooks Permalink Get a link to this section

A webhook is a subscription that notifies you when a Square event occurs. For more information about using webhooks, see Webhooks Overview.

The Terminal API uses the following webhook events:

terminal.action.createdA TerminalAction request was created.
terminal.action.updatedA TerminalAction request was updated.
terminal.checkout.createdA TerminalCheckout request was created.
terminal.checkout.updatedA TerminalCheckout status was changed.
terminal.refund.createdA TerminalRefund request was created.
terminal.refund.updatedA TerminalRefund status was changed.

For a complete list of webhook events, see V2 Webhook Events Reference.

Your POS application should monitor the state of any Terminal checkout requests by subscribing to the Terminal API webhook events.

Related topics Permalink Get a link to this section

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