Applies to: Terminal API | Devices API | Payments API | Refunds API
Use the Terminal API to connect a custom POS application with a Square Terminal.
The Terminal API lets developers integrate Square in-person payments so that your custom Point of Sale (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 integrates with a POS application to send and receive API calls. 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 complete the pairing, follow the steps in POS Application Pairing with Square Terminal.
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 isn't 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.
Important
Checkouts in the
COMPLETEDorCANCELEDstate are deleted after 30 days. The Payment object serves as your permanent record.Square Terminals don't support connecting to external printers when the Square Terminal is paired.
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 payments and e-money card payments are also accepted. For more information about payment card support by region, see Card present for in-person payment.
The Terminal API doesn't 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 doesn't cover the full payment amount, you can create a second checkout request to pay the remaining balance.
Square Terminal doesn't support cash payments. Instead, use the Payments API to take the cash payment and record the payment using CreatePayment. For more information, see Take Cash Payments.
The following payment options are available only in the US for Terminal API:
| Payment option | Description |
|---|---|
| Application fees | Collect application fees from payments. |
| Delayed capture | Set up delayed capture of payments. This includes actions to be applied to delayed capture payments after the delay duration time has elapsed. |
| Orders and itemizations | Link an order and an order's line items to a Terminal checkout. |
| Split tender | Apply multiple in-person payments to an order. |
| Statement description identifiers | Add a statement description identifier to the checkout request. The identifier can contain a customer ID or an order object ID. |
| Tip money | Collect tips as money at checkout. |
Important
If the seller has a Square account that's not based in the US, you might encounter an error with Terminal checkout requests if the request contains fields for options not supported in the US. For example, the order_id field cannot be used for checkout requests from a non-US Square account.
For more information about adding these payment options to a Terminal checkout request, see Take Payments with the Terminal API.
For a payment that involves split tender, the seller creates multiple Terminal checkout requests that address each part of the total payment amount. The buyer can then settle the portions of the total payment with different payment methods.
During a partial authorization, the seller creates a Terminal checkout request for the total payment amount, and includes a payment method where the buyer's payment method has insufficient funds (for example, a gift card with an insufficient balance).
You can test your Terminal API integration in the Square Sandbox without Square Terminal hardware interactions. Use these Sandbox test values to test your integration against successful and failed Terminal checkout requests.
When using a Sandbox device ID, you can test the Terminal checkout process and verify the checkout status change. In production, you should use Terminal API webhooks to get a checkout response notification because there can be a significant delay between requesting a checkout and the completion of the checkout. To learn more about subscribing to webhooks, see Subscribe to Event Notifications.
For Canadian sellers who want to refund payments on Interac 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 includes a true value in the refund_requires_card_presence field to identify when the Terminal API refund is to be used.
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.
Important
Terminal actions are currently in Beta.
For more information, see Manage Terminal Actions.
A webhook is a subscription that notifies you when a Square event occurs. For more information, see Square Webhooks.
The Terminal API uses the following webhook events:
| Event | Permission | Description |
|---|---|---|
| terminal.checkout.created | PAYMENTS_READ | A TerminalCheckout request was created. |
| terminal.checkout.updated | PAYMENTS_READ | A TerminalCheckout status was changed. |
| terminal.refund.created | PAYMENTS_READ | A TerminalRefund request was created. |
| terminal.refund.updated | PAYMENTS_READ | A TerminalRefund status was changed. |
| terminal.action.created | PAYMENTS_READ | A TerminalAction request was created. |
| terminal.action.updated | PAYMENTS_READ | A TerminalAction status was updated. |
For a complete list of webhook events, see Webhook Events Reference.
Your POS application should monitor the state of any Terminal checkout requests by subscribing to the Terminal API webhook events.