Terminal API Integration with a POS Application and Square Terminal
Use the Terminal API to connect a custom point-of-sale application with a Square Terminal.
The Terminal API lets developers integrate Square in-person payments so that your custom POS application can take full advantage of Square Terminal and its features. Square Terminal enables in-person payments with card chip and NFC payments, addresses EMV certification requirements, and ensures PCI compliance.
The Terminal API is compatible with any software platform or operating system that runs the POS application. Depending on your seller's use case, you might need to integrate your POS application with the Reader SDK and connect to a Square Reader or Square Stand.
The integration works with a checkout flow as follows:
Pair a Square Terminal and a POS application using the Devices API.
To learn how the pairing works, see POS Application Integration with the Terminal API.
Send requests for payment checkouts with the Terminal API.
Learn how the checkout process works in the next 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 screen behavior of the Square Terminal payment.
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 application 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 the
CANCELED state are deleted after 30 days. The Payment object serves as your permanent record.
To get started with sending Terminal checkout requests, see Take Payments with the Terminal API.
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, PayPay QR code and e-money card payments are also accepted. For more information about payment card support by region, see Supported Payment Cards by Country.
The Terminal API does not support splitting a checkout into multiple payments for a single checkout request. Instead, you must use the POS application to split the payment. You can also create a partial payment checkout request with a gift card. If the gift card does not cover the full payment amount, you can create a second checkout request to pay the remaining balance.
|App fee||Collect signature||Collect tip||Delayed capture||E-Money payments||Itemized order|
|Partial authorization||Payment autocomplete||PayPay QR code payment||Refund Interac Payments||Terminal action|
The Terminal API provides additional ways for a Square Terminal and your POS application to interact, beyond accepting payments and refunds. These interactions are known as Terminal actions, which allow you to build non-payment related workflows for the seller such as saving a card on file or checking the status of a Square Terminal.
Terminal actions are currently in beta.
For more information, see Advanced Features.
A webhook is a subscription that notifies you when a Square event occurs. For more information about using webhooks, see Square Webhooks Overview.
The Terminal API uses the following webhook events:
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.