TerminalCheckouts

Create and query Square Terminal checkout requests.

Table Specific Information

Select

The component uses the Square API to filter the results by the following columns and operators while the rest of the filter is executed client-side within the component.

Id supports the following operator: =.
CreatedAt supports the following operators: =, >=, <=, >, <.
DeviceOptionsDeviceId supports the following operator: =.
Status supports the following operator: =.

Retrieve all terminal checkouts:

SELECT * FROM TerminalCheckouts

Retrieve a specific terminal checkout:

SELECT * FROM TerminalCheckouts WHERE Id = 'checkout_id_here'

Retrieve pending terminal checkouts:

SELECT * FROM TerminalCheckouts WHERE Status = 'PENDING'

Retrieve terminal checkouts for a specific device:

SELECT * FROM TerminalCheckouts WHERE DeviceOptionsDeviceId = '995CS397A6475287'

Insert

To create a terminal checkout, you must specify the AmountMoneyAmount, AmountMoneyCurrency, DeviceOptionsDeviceId, and IdempotencyKey columns.

INSERT INTO TerminalCheckouts (AmountMoneyAmount, AmountMoneyCurrency, DeviceOptionsDeviceId, IdempotencyKey) VALUES (100, 'USD', 'DEVICE_ID', 'unique-idempotency-key')

Columns


Name	Type	ReadOnly	Description
Id [KEY]	String	True	The unique ID of this checkout.
AmountMoneyAmount	Int64	False	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.
AmountMoneyCurrency	String	False	The currency of the charge, in ISO 4217 format (e.g., USD). The allowed values are UNKNOWN_CURRENCY, AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SLE, SOS, SRD, SSP, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USN, USS, UYI, UYU, UZS, VEF, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XOF, XPD, XPF, XPT, XTS, XXX, YER, ZAR, ZMK, ZMW, BTC, XUS.
PaymentType	String	False	The type of payment the terminal should attempt to capture from. Defaults to CARD_PRESENT. The allowed values are CARD_PRESENT, MANUAL_CARD_ENTRY, FELICA_ID, FELICA_QUICPAY, FELICA_TRANSPORTATION_GROUP, FELICA_ALL, QR_CODE, PAYPAY.
DeviceOptionsDeviceId	String	False	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.
DeviceOptionsSkipReceipt	Boolean	False	Instructs the device to skip the receipt screen. Defaults to false.
DeviceOptionsTipSettingsAllowTipping	Boolean	False	Indicates whether tipping is enabled for this checkout. Defaults to false.
DeviceOptionsTipSettingsSeparateTipScreen	Boolean	False	Indicates whether tip options should be presented on the screen before presenting the signature screen during card payment. Defaults to false.
DeviceOptionsTipSettingsCustomTipField	Boolean	False	Indicates whether custom tip amounts are allowed during the checkout flow. Defaults to false.
DeviceOptionsTipSettingsTipPercentages	String	False	A list of tip percentages to present during the checkout flow, specified as up to 3 non-negative integers from 0 to 100 (inclusive). Defaults to 15, 20, and 25.
DeviceOptionsTipSettingsSmartTipping	Boolean	False	Enables the Smart Tip Amounts behavior. Exact tipping options depend on the region. When set to true, the tip_percentages setting is ignored. Defaults to false.
DeviceOptionsCollectSignature	Boolean	False	Indicates that signature collection is desired during checkout. Defaults to false.
DeviceOptionsShowItemizedCart	Boolean	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.
DeviceOptionsAllowAutoCardSurcharge	Boolean	False	(Beta) Controls whether the mobile client applies Auto Card Surcharge (ACS) during checkout. If true, ACS is applied based on Dashboard configuration. If false, ACS is not applied regardless of that configuration.
PaymentOptionsAutocomplete	Boolean	False	Indicates whether the Payment objects created from this TerminalCheckout are automatically COMPLETED or left in an APPROVED state for later modification. Default: true.
PaymentOptionsDelayDuration	String	False	The duration after payment creation when Square automatically resolves pending payments. RFC 3339 format, minimum 1 minute, maximum 36 hours. Only for card payments with delayed capture (autocomplete=false). Default: PT36H.
PaymentOptionsAcceptPartialAuthorization	Boolean	False	When enabled for Square Gift Card transactions, allows payments to return amounts less than requested. Only works with delayed capture (autocomplete=false). Default: false.
PaymentOptionsDelayAction	String	False	The action to be applied to the Payment when the delay_duration has elapsed. Must be CANCEL or COMPLETE. Cannot be COMPLETE if an order_id is present. Only for delayed capture (autocomplete=false). Default: CANCEL. The allowed values are CANCEL, COMPLETE.
ReferenceId	String	False	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.
Note	String	False	An optional note to associate with the checkout, as well as with any payments used to complete the checkout. Maximum 500 characters.
OrderId	String	False	The reference to the Square order ID for the checkout request.
CustomerId	String	False	An optional ID of the customer associated with the checkout.
AppFeeMoneyAmount	Int64	False	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.
AppFeeMoneyCurrency	String	False	The currency of the app fee, in ISO 4217 format. For example, the currency code for US dollars is USD. The allowed values are UNKNOWN_CURRENCY, AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYR, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, CNY, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HRK, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LTL, LVL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRO, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLL, SLE, SOS, SRD, SSP, STD, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USN, USS, UYI, UYU, UZS, VEF, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XOF, XPD, XPF, XPT, XTS, XXX, YER, ZAR, ZMK, ZMW, BTC, XUS.
Status	String	True	The status of the TerminalCheckout. Options: PENDING, IN_PROGRESS, CANCEL_REQUESTED, CANCELED, COMPLETED. The allowed values are PENDING, IN_PROGRESS, CANCEL_REQUESTED, CANCELED, COMPLETED.
LocationId	String	True	The location of the device where the TerminalCheckout was directed.
AppId	String	True	The ID of the application that created the checkout.
TipMoneyAmount	Int64	False	The amount designated as a tip, in addition to amount_money. This may only be set for a checkout that has tipping disabled (tip_settings.allow_tipping is false).
TipMoneyCurrency	String	False	The currency of the tip collected.
CreatedAt	Datetime	True	A read-only timestamp in RFC 3339 format when this checkout was created.
UpdatedAt	Datetime	True	A read-only timestamp in RFC 3339 format when this checkout was last updated.
CancelReason	String	True	The reason why TerminalCheckout is canceled. Present if the status is CANCELED. The allowed values are BUYER_CANCELED, SELLER_CANCELED, TIMED_OUT.
PaymentIds	String	True	The list of IDs of payments created through this checkout. Populated after payment is completed.
TeamMemberId	String	False	An optional ID of the team member associated with creating the checkout.
StatementDescriptionIdentifier	String	False	Optional additional payment information to include on the customer card statement as part of the statement description. This can be, for example, an invoice number, ticket number, or short description that uniquely identifies the purchase. Maximum 20 characters.

Pseudocolumns

Pseudo column fields are used in the WHERE clause of SELECT statements (unless stated otherwise) and offer a more granular control over the tuples that are returned from the data source.