Square Terminal Integration Overview
Use the Terminal API and Devices API to pair a custom point-of-sale (POS) application with a Square Terminal and take in-person payments with payment cards.
On this page
The Terminal and Devices APIs let developers integrate Square in-person payments in all supported areas and Canadian Interac refunds in custom POS applications using a Square Terminal. This simplifies chip and NFC payments, addresses EMV certification requirements, and makes PCI compliance easy. Square Terminal supports authorization and transaction processing.
A POS client cannot be physically connected to a Square Terminal but must be paired through a wireless connection before a checkout can be processed.
The Devices API handles the wireless connection and pairs a POS client with a Square Terminal. When the Square Terminal is paired, the POS client can send checkout requests using the Terminal API. The Square Terminal gets payment information from the request and collects the payment from the buyer.
The Devices API creates a device code for the seller to use in signing in to a Square Terminal and then provides the device ID of the paired Square Terminal for use in 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.
You can see the state of all pairs on the Seller Dashboard by choosing Accounts & Settings, and then choosing Devices.
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.
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 states are DELETED after 30 days. The Payment object serves as your permanent record.
The Terminal API supports payment cards and NFC payments like Apple Pay and Google Pay. Payment cards include Square Gift Cards, credit cards, debit cards, and prepaid debit cards. 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.