Creates a Terminal checkout request and sends it to the specified device to take a payment for the requested amount.
Open in API Reference
The checkout to create.
The amount of money (including the tax amount) that the Square Terminal device should try to collect.
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.
currency
USD
amount
The type of currency, in ISO 4217 format. For example, the currency code for US dollars is USD.
A string that contains no characters. In an API request this value will appear as ''. Can be used to remove a field’s value.
''
Options to control the display and behavior of the Square Terminal device.
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.
TerminalCheckout
DeviceCode
DeviceCode.device_id
device_id
Indicates that signature collection is desired during checkout. Defaults to false.
Show the itemization screen prior to taking a payment. This field is only meaningful when the checkout includes an order ID. Defaults to true.
Instructs the device to skip the receipt screen. Defaults to false.
Tip-specific settings.
The amount the developer is taking as a fee for facilitating the payment on behalf of the seller.
The amount cannot be more than 90% of the total amount of the payment.
The amount must be specified in the smallest denomination of the applicable currency (for example, US dollar amounts are specified in cents). For more information, see Working with Monetary Amounts.
The fee currency code must match the currency associated with the seller that is accepting the payment. The application must be from a developer account in the same country and using the same currency code as the seller.
For more information about the application fee scenario, see Take Payments and Collect Fees.
To set this field, PAYMENTS_WRITE_ADDITIONAL_RECIPIENTS OAuth permission is required. For more information, see Permissions.
An optional ID of the customer associated with the checkout.
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.
PENDING
CANCELED
TIMED_OUT
Default: 5 minutes from creation
Maximum: 5 minutes
Example for 2 days, 12 hours, 30 minutes, and 15 seconds: P2DT12H30M15S
An optional note to associate with the checkout, as well as with any payments used to complete the checkout. Note: maximum 500 characters
The reference to the Square order ID for the checkout request.
Payment-specific options. Used for 3rd party developers.
If set to true and charging a Square Gift Card, a payment might be returned with amount_money equal to less than what was requested. For example, a request for $20 when charging a Square Gift Card with a balance of $5 results in an APPROVED payment of $5. You might choose to prompt the buyer for an additional payment to cover the remainder or cancel the Gift Card payment.
true
amount_money
This field cannot be true when autocomplete = true. This field cannot be true when an order_id isn't specified.
autocomplete = true
order_id
For more information, see Take Partial Payments.
Default: false
Indicates whether the Payment objects created from this TerminalCheckout are automatically COMPLETED or left in an APPROVED state for later modification.
Payment
COMPLETED
APPROVED
The duration of time after the payment's creation when Square automatically cancels the payment. This automatic cancellation applies only to payments that do not reach a terminal state (COMPLETED, CANCELED, or FAILED) before the delay_duration time period.
delay_duration
This parameter should be specified as a time duration, in RFC 3339 format, with a minimum value of 1 minute.
Note: This feature is only supported for card payments. This parameter can only be set for a delayed capture payment (autocomplete=false). Default:
autocomplete=false
The type of payment the terminal should attempt to capture from. Defaults to CARD_PRESENT.
CARD_PRESENT
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.
A unique string that identifies this CreateCheckout request. Keys can be any valid string but must be unique for every CreateCheckout request.
CreateCheckout
See Idempotency keys for more information.
// No response received yet.