POST /v2/terminals/checkouts

Creates a Terminal checkout request and sends it to the specified device to take a payment for the requested amount.

Servers

https://connect.squareup.com

Request headers

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"

Request body fields

Name	Type	Required	Description
`checkout`	Object	Yes
`checkout.payment_ids[]`	Array	No	A list of IDs for payments created by this `TerminalCheckout`.
`checkout.cancel_reason`	String	No	Present if the status is `CANCELED`.
`checkout.deadline_duration`	String	No	An RFC 3339 duration, after which the checkout is automatically canceled. A `TerminalCheckout` that is `PENDING` is automatically `CANCELED` and has a cancellation reason of `TIMED_OUT`. Default: 5 minutes from creation Maximum: 5 minutes
`checkout.payment_type`	String	No	The type of payment the terminal should attempt to capture from. Defaults to `CARD_PRESENT`.
`checkout.app_id`	String	No	The ID of the application that created the checkout.
`checkout.device_options`	Object	Yes
`checkout.device_options.skip_receipt_screen`	Boolean	No	Instructs the device to skip the receipt screen. Defaults to false.
`checkout.device_options.device_id`	String	Yes	The unique ID of the device intended for this `TerminalCheckout`. A list of `DeviceCode` objects can be retrieved from the /v2/devices/codes endpoint. Match a `DeviceCode.device_id` value with `device_id` to get the associated device code.
`checkout.device_options.tip_settings`	Object	No
`checkout.device_options.tip_settings.separate_tip_screen`	Boolean	No	Indicates whether tip options should be presented on the screen before presenting the signature screen during card payment. Defaults to false.
`checkout.device_options.tip_settings.allow_tipping`	Boolean	No	Indicates whether tipping is enabled for this checkout. Defaults to false.
`checkout.device_options.tip_settings.custom_tip_field`	Boolean	No	Indicates whether custom tip amounts are allowed during the checkout flow. Defaults to false.
`checkout.device_options.tip_settings.smart_tipping`	Boolean	No	Enables the "Smart Tip Amounts" behavior. Exact tipping options depend on the region in which the Square seller is active. For payments under 10.00, in the Australia, Canada, Ireland, United Kingdom, and United States, tipping options are presented as no tip, .50, 1.00 or 2.00. For payment amounts of 10.00 or greater, tipping options are presented as the following percentages: 0%, 5%, 10%, 15%. If set to true, the `tip_percentages` settings is ignored. Defaults to false. To learn more about smart tipping, see Accept Tips with the Square App.
`checkout.device_options.tip_settings.tip_percentages[]`	Array	No	A list of tip percentages that should be presented during the checkout flow, specified as up to 3 non-negative integers from 0 to 100 (inclusive). Defaults to 15, 20, and 25.
`checkout.status`	String	No	The status of the `TerminalCheckout`. Options: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`, `COMPLETED`
`checkout.reference_id`	String	No	An optional user-defined reference ID that can be used to associate this `TerminalCheckout` to another entity in an external system. For example, an order ID generated by a third-party shopping cart. The ID is also associated with any payments used to complete the checkout.
`checkout.updated_at`	String	No	The time when the `TerminalCheckout` was last updated, as an RFC 3339 timestamp.
`checkout.id`	String	No	A unique ID for this `TerminalCheckout`.
`checkout.location_id`	String	No	The location of the device where the `TerminalCheckout` was directed.
`checkout.note`	String	No	An optional note to associate with the checkout, as well as with any payments used to complete the checkout.
`checkout.created_at`	String	No	The time when the `TerminalCheckout` was created, as an RFC 3339 timestamp.
`checkout.amount_money`	Object	Yes	Represents an amount of money. `Money` fields can be signed or unsigned. Fields that do not explicitly define whether they are signed or unsigned are considered unsigned and can only hold positive amounts. For signed fields, the sign of the value indicates the purpose of the money transfer. See Working with Monetary Amounts for more information.
`checkout.amount_money.amount`	Integer	No	The amount of money, in the smallest denomination of the currency indicated by `currency`. For example, when `currency` is `USD`, `amount` is in cents. Monetary amounts can be positive or negative. See the specific field description to determine the meaning of the sign in a particular case.
`checkout.amount_money.currency`	String	No	The type of currency, in ISO 4217 format. For example, the currency code for US dollars is `USD`. See Currency for possible values.
`idempotency_key`	String	Yes	A unique string that identifies this `CreateCheckout` request. Keys can be any valid string but must be unique for every `CreateCheckout` request. See Idempotency keys for more information.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.