---
title: "CreateTerminalCheckout"
method: POST
path: "/v2/terminals/checkouts"
tags: ["Terminal"]
---

# CreateTerminalCheckout

`POST /v2/terminals/checkouts`

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

## Request body

- CreateTerminalCheckoutRequest
  - `checkout` TerminalCheckout, required
    - `amount_money` Money, required — 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](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information.
      - `amount` integer — 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` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values.
    - `app_id` string — The ID of the application that created the checkout.
    - `cancel_reason` string — Present if the status is `CANCELED`.
    - `created_at` string — The time when the `TerminalCheckout` was created, as an RFC 3339 timestamp.
    - `deadline_duration` string — 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
    - `device_options` DeviceCheckoutOptions, required
      - `device_id` string, required — 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.
      - `skip_receipt_screen` boolean — Instructs the device to skip the receipt screen. Defaults to false.
      - `tip_settings` TipSettings
        - `allow_tipping` boolean — Indicates whether tipping is enabled for this checkout. Defaults to false.
        - `custom_tip_field` boolean — Indicates whether custom tip amounts are allowed during the checkout flow. Defaults to false.
        - `separate_tip_screen` boolean — Indicates whether tip options should be presented on the screen before presenting the signature screen during card payment. Defaults to false.
        - `smart_tipping` boolean — 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](https://squareup.com/help/us/en/article/5069-accept-tips-with-the-square-app).
        - `tip_percentages` integer[] — 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.
    - `id` string — A unique ID for this `TerminalCheckout`.
    - `location_id` string — The location of the device where the `TerminalCheckout` was directed.
    - `note` string — An optional note to associate with the checkout, as well as with any payments used to complete the checkout.
    - `payment_ids` string[] — A list of IDs for payments created by this `TerminalCheckout`.
    - `payment_type` string — The type of payment the terminal should attempt to capture from. Defaults to `CARD_PRESENT`.
    - `reference_id` string — 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.
    - `status` string — The status of the `TerminalCheckout`. Options: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`, `COMPLETED`
    - `updated_at` string — The time when the `TerminalCheckout` was last updated, as an RFC 3339 timestamp.
  - `idempotency_key` string, required — 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](https://developer.squareup.com/docs/basics/api101/idempotency) for more information.

## Response `200`

Success

- CreateTerminalCheckoutResponse
  - `checkout` TerminalCheckout
    - `amount_money` Money, required — 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](https://developer.squareup.com/docs/build-basics/working-with-monetary-amounts) for more information.
      - `amount` integer — 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` string — The type of currency, in __ISO 4217 format__. For example, the currency code for US dollars is `USD`. See [Currency](https://developer.squareup.com/reference/square_2021-08-18/enums/Currency) for possible values.
    - `app_id` string — The ID of the application that created the checkout.
    - `cancel_reason` string — Present if the status is `CANCELED`.
    - `created_at` string — The time when the `TerminalCheckout` was created, as an RFC 3339 timestamp.
    - `deadline_duration` string — 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
    - `device_options` DeviceCheckoutOptions, required
      - `device_id` string, required — 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.
      - `skip_receipt_screen` boolean — Instructs the device to skip the receipt screen. Defaults to false.
      - `tip_settings` TipSettings
        - `allow_tipping` boolean — Indicates whether tipping is enabled for this checkout. Defaults to false.
        - `custom_tip_field` boolean — Indicates whether custom tip amounts are allowed during the checkout flow. Defaults to false.
        - `separate_tip_screen` boolean — Indicates whether tip options should be presented on the screen before presenting the signature screen during card payment. Defaults to false.
        - `smart_tipping` boolean — 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](https://squareup.com/help/us/en/article/5069-accept-tips-with-the-square-app).
        - `tip_percentages` integer[] — 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.
    - `id` string — A unique ID for this `TerminalCheckout`.
    - `location_id` string — The location of the device where the `TerminalCheckout` was directed.
    - `note` string — An optional note to associate with the checkout, as well as with any payments used to complete the checkout.
    - `payment_ids` string[] — A list of IDs for payments created by this `TerminalCheckout`.
    - `payment_type` string — The type of payment the terminal should attempt to capture from. Defaults to `CARD_PRESENT`.
    - `reference_id` string — 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.
    - `status` string — The status of the `TerminalCheckout`. Options: `PENDING`, `IN_PROGRESS`, `CANCEL_REQUESTED`, `CANCELED`, `COMPLETED`
    - `updated_at` string — The time when the `TerminalCheckout` was last updated, as an RFC 3339 timestamp.
  - `errors` Error[] — Information about errors encountered during the request.
    - `category` string, required — The high-level category for the error.
    - `code` string, required — The specific code of the error.
    - `detail` string — A human-readable description of the error for debugging purposes.
    - `field` string — The name of the field provided in the original request (if any) that the error pertains to.

---

[API](https://skmtc.net/square/apis/squareup.md) · [All operations](https://skmtc.net/square/apis/squareup/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/square/squareup/revisions/8d95e3639487/schema)