Skip to navigation

Complete Checkout Session

View as Markdown

Mark a checkout session as completed.

Works for both User and API Key authentication. Account access is automatically validated via endpoint dependency.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

external_idstringRequired
account_idstringRequired

Headers

Idempotency-Keystring or nullOptional>=8 characters
A unique key for this request. A retry with the same key returns the first response instead of running again, for 24 hours. Keys are per caller.

Response

Successful Response
idstring
Unique checkout session identifier
account_idstring
Account identifier
secure_tokenstring
Secure token for accessing the checkout session
expires_in_hoursinteger
Number of hours until the checkout session expires
completedboolean
Whether the checkout session has been completed
stateenum
Computed state of the checkout session
Allowed values:
is_expiredboolean
Whether the checkout session has expired
success_urlstring
URL to redirect to on success
return_urlstring
URL to return to on cancellation
card_tokenization_modeenum

Card tokenization mode: ‘direct’ (KMS encryption) or ‘vgs’ (VGS Collect + proxy)

Allowed values:
created_atdatetime
When the checkout session was created
updated_atdatetime
When the checkout session was last updated
customer_idstring or nullOptional
Customer identifier
customer_emailstring or nullOptional
Customer email address
apply_customer_balancebooleanOptionalDefaults to true

Whether invoices created from this session apply the customer’s credit balance. False leaves the credit untouched for a later purchase; a negative balance (an amount the customer owes) is handled as on a default session.

line_itemslist of objectsOptional
List of line items in the checkout session
coupon_idstring or nullOptional
ID of the coupon applied to this checkout session
promotion_codestring or nullOptional
Promotion code used to apply the coupon
free_trial_daysinteger or nullOptional

Free trial length in days applied to the subscription this session creates: the value sent on create, else the trial of the recurring prices when every line is recurring. Null when there is no trial.

card_checkout_settingsobjectOptional

Settings for card checkout behavior (parallel setup, 3DS mode)

cascade_statusobject or nullOptional

Cascade pricing status (None if no cascade configured)

cascade_tierslist of objects or nullOptional

Full cascade tier details including processor routes (None if no cascade configured)

processor_route_idstring or nullOptional

ID of the processor route used for card checkout. A processor route contains an ordered list of processors tried sequentially as a fallback chain. This is a single route ID, not an array — to use multiple processors, define them within the route itself.

inline_routeobject or nullOptional

Inline route defined directly on this session. Null if a predefined processor_route_id is used instead, or if no route is configured.

modeenumOptional
Checkout session mode
Allowed values:
setup_preferencesmap from strings to any or nullOptional
Preferences for payment method setup
custom_fieldsmap from strings to any or nullOptional

Custom field values. Only included when expand=custom_fields is specified.

params_for_subobject or nullOptional
Parameters to pass to the subscription when created from this checkout session.
statement_descriptor_suffixstring or nullOptional
Statement descriptor suffix for this checkout session. Applied to the charge made from this session and copied onto any subscription created from it, so renewals inherit it. Null when not set.
statement_descriptor_overridesmap from strings to strings or maps from strings to strings or nullOptional

FULL statement descriptor override map, keyed by processor id (proc_…). When a charge runs on a keyed processor, its value is sent as the whole descriptor and takes precedence over the processor’s own statement descriptor and statement descriptor prefix. Two shapes are accepted. Flat: {“proc_…”: “DESCRIPTOR”} applies to every charge. By charge type: {“one_time”: {“proc_…”: ”…”}, “trial_conversion”: {…}, “recurring”: {…}} picks the descriptor by the kind of charge: one_time is a checkout charge that starts no subscription; trial_conversion is the first paid renewal of a subscription that had a trial, including its retries; recurring is every other subscription charge, including the first charge of a subscription with no trial. When the charge’s type has no entry for the processor, a trial_conversion charge uses the recurring entry, then the processor’s own statement descriptor; a one_time charge uses the processor’s own statement descriptor, else the prefix (the processor’s statement descriptor prefix, else the account prefix) plus the checkout’s suffix, and never the recurring entry. The two shapes cannot be mixed, and only one_time, trial_conversion and recurring are valid charge types (422 otherwise). Supported processors: Adyen, Checkout.com, Authorize.net, Airwallex and NMI. Stripe, PayPal, Braintree and other processors are not allowed as keys (422). Caveats: Authorize.net applies it only on TSYS/EVO-backed accounts; Airwallex applies it only after dynamic descriptors are enabled on the Airwallex account; NMI applies it only when custom descriptors are allowed on the processor. Copied onto any subscription created from this session. Null when not set.

Errors

422
Unprocessable Entity Error