Applies to: Terminal API | Orders API
Learn how to use the Terminal API to process payments for orders created through the Orders API.
The Terminal API supports the lifecycle of an order by integrating the Square Terminal and the Orders API. The Orders API enables the purchase of line items, calculates totals, confirms payments, tracks an order's progress through fulfillment, itemizes purchases, and generates receipts all within a CreateTerminalCheckout request. With support for orders interoperability, you can build complex payment workflows using the Terminal API with an order.
The Terminal API's integration with orders and itemization lets you build workflows that process complex payments on the Square Terminal, such as splitting payments for a restaurant order that itemizes several menu line items. With this integration, you can use Square products like Square Order Manager to manage orders that have been paid and processed by the Square Terminal.
- Square Terminal version 6.62 or later.
- Support for orders and itemization with the Square Terminal. For more information about regional support, see Take Payments on Hardware.
The Terminal API doesn't support updates made to orders after the Terminal checkout with the
order_idmoves to theIN_PROGRESSstate, which indicates that the Square Terminal is currently processing the checkout.Any updates made to the order while the Terminal checkout is in the
IN_PROGRESSstate might lead to errors on the Square Terminal during checkout, and problems with resolving the order.To correctly update an order after a Terminal checkout has already been created, send a cancel request using CancelTerminalCheckout.
If you successfully canceled the Terminal checkout and the order is still
OPEN, update the order and create a new Terminal checkout with the same order. You can also create a new order and use itsorder_idto create a new Terminal checkout.Order must be
OPEN.Square deletes completed checkouts after 30 days. If you need to store the Terminal checkouts for future reference, retain the checkout's payment IDs.
An Order object is a top-level container representing an order. The order can have line items attached to it to indicate that the order consists of the items attached. A Terminal checkout can link to an open order and allow a buyer to complete a payment on that order. The Square Terminal displays the itemized list of purchased items during checkout and on the printed and digital receipts.
The following procedure shows how to use the Terminal API to process payments with an order.
Using the Terminal API with orders and itemization support, create an Order object using the Orders API CreateOrder endpoint, representing an order for a total amount of $5.00 USD, with two $1.00 items and a single $3.00 item.
Create order
- Pass the order's
order_idto a new Terminal checkout request to collect any payments associated with the order. - Set the
show_itemized_cartvalue totruein the Terminal checkout's DeviceCheckoutOptions property. This property shows the itemization screen on the Square Terminal prior to taking a payment. This field is active only if the Terminal checkout includes theorder_id. - Pass the rest of the details in the
checkoutproperty fields of the request.
Create terminal checkout
The CreateOrder response returns an order_id value, which you can pass into the order_id field in the CreateTerminalCheckout request. If the Terminal checkout request is successful, the amount_money value from the Terminal checkout is applied to the order.
The following image demonstrates how the Square Terminal shows a checkout order for coffee and a croissant, with discounts and service charges applied prior to the buyer confirming and paying for the order.
By default, Terminal checkouts are designed to pay the full order total. In this case:
- The Terminal checkout sets
autocompletetotrue. - The Terminal checkout amount must equal the order total.
- The order automatically transitions to a
COMPLETEDstate when the checkout completes.
If autocomplete is set to false in the Terminal checkout, you can submit partial payments against the order, such as for splitting a restaurant bill between two cards. In this partial payment flow, the order does not move to a COMPLETED state automatically. To process all partial payments, you need to call PayOrder and include all payment IDs. For more information, see Pay for Orders.
Create an order with the Orders API.
Create one or more Terminal checkouts for part of the order total. Assign the
order_idand verifyautocomplete=falsewhen calling Terminal API.Collect the
payment_idfrom each Terminal checkout and any other payments created such as for cash payments.Call the PayOrder endpoint with all of the payment IDs.
After calling PayOrder, the order's status changes to COMPLETED. The associated partial payments' statuses are also changed to COMPLETED.
Split tenders are available in regions that support order IDs for checkouts.
Including the order_id in the Terminal checkout request allows the Square Terminal to print a paper and digital receipt with itemization.
By default, the buyer sees the receipt options screen on the Terminal checkout and chooses a method to receive the receipt. The Square Terminal provides an itemized receipt using its built-in printer or a link to view the digital link from the buyer's email or a text message sent to the buyer's phone number.
The following animation shows the Square Terminal accepting a card payment and displaying the receipt options.
You can set the following additional receipt options:
By default, the skip_receipt_screen property is set to false. If this property is set to true, the Square Terminal skips the receipt options screen during checkout.
Create terminal checkout
You can set the Square Terminal to automatically print a receipt. This setting overrides the skip_receipt_screen value from the Terminal checkout request and doesn't display the receipt options screen.
To set the option to automatically print receipts on the Square Terminal, tap Hardware, Printer, Receipts, Print Receipts, and Automatically.
The following animation demonstrates how to set this option.
For Square accounts in Japan, the Square Terminal prints both a standard receipt and a formal receipt called ryoshusho (領収書).
The Square Terminal provides the formal receipt option on the Receipt Options screen.
You can reissue formal receipts after checkout by using the RECEIPT Terminal action and include the payment_id that's returned from the completed Terminal checkout. For more information, see Display the receipt options screen.
Square Terminal supports processing other types of payments and additional checkout features. For more information, see Additional Payment and Checkout Features.