Skip to navigation

Create Checkout Session

View as Markdown

Create a new checkout session with line items.

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

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.

Request

This endpoint expects an object.
success_urlstringRequired
URL to redirect to on success
return_urlstringRequired
URL to return to on cancellation
modeenumOptional
Checkout session mode. 'payment' charges for line items, 'setup' saves a payment method without charging.
Allowed values:
customer_idstring or nullOptional

Customer identifier. The customer must belong to this account (404 otherwise). Attaching a customer exposes that customer’s saved payment methods and credit balance to whoever holds this checkout session’s token, so attach only a customer you have identified and authenticated yourself (for example a signed-in shopper), never one matched from details the shopper typed in.

default_payment_method_idstring or nullOptional

A saved payment method to suggest first for a one-click checkout. This is a prefill hint, NOT a binding — the customer can pick a different card, and the confirm request is authoritative for what is charged. Requires payment mode and a customer_id, and the payment method must belong to that customer and this account.

saved_card_cvc_repromptboolean or nullOptional

Whether the saved-card one-click re-collects the card security code (CVC) at confirm for THIS session. Omitted defaults to false (pure one-click, no CVC). Set true for best approval rates, and required when the session routes to Adyen (Adyen 422 14_029 on a stored-card charge with no CVC).

expires_in_hoursinteger or nullOptional

Number of hours until the checkout session expires. When omitted, the account’s configured checkout session expiration (checkout_settings.session_expiration_minutes) is used.

apply_customer_balancebooleanOptionalDefaults to true

Whether the invoice created from this session applies the customer’s credit balance. Set false to leave the credit untouched for a later purchase (for example when a promo code should not stack with a referral credit). The customer then pays the full amount after coupons. Only credit is skipped: a negative balance (an amount the customer owes) is handled exactly as on a default session. Applies to this session’s invoice only; subscription renewals, and the first paid invoice after a free trial, still apply the balance. Cannot be changed after the session is created: an update that sends it returns 422.

line_itemslist of objectsOptional
List of line items
coupon_idstring or nullOptional
ID of the coupon to apply to this checkout session
promotion_codestring or nullOptional
Promotion code to use for applying a coupon discount
free_trial_daysinteger or nullOptional0-730

Free trial length in days for the subscription this session creates. Omit it to use the trial set on the recurring price (the shortest one when several prices carry a trial); a basket that also holds a one-time price takes no trial by default, because the trial would zero that line too. Send 0 to start the subscription without a trial even when the price has one. A value above 0 requires at least one recurring price and is rejected in ‘setup’ mode. During the trial the first invoice is $0: the card is saved and charged when the trial ends.

card_checkout_settingsobject or nullOptional

Settings for card checkout behavior (parallel setup, 3DS mode). Defaults apply if not provided.

processor_route_idstring or nullOptional

ID of a processor route to use for card checkout (overrides account default). A processor route contains an ordered list of processors tried sequentially as a fallback chain. Pass a single route ID — to use multiple processors, define them within the route itself.

inline_routeobject or nullOptional

Define processors directly on this session instead of referencing a predefined route. The processors are tried in order as a fallback chain. Mutually exclusive with processor_route_id — set one or the other, not both. Use this for one-off routing configurations; use processor_route_id for reusable routes shared across sessions.

custom_fieldsmap from strings to any or nullOptional

Custom field values to set on this checkout session. Keys must match defined field keys for the checkout_session entity type. Set a key to null to delete that field’s value.

cascade_line_itemslist of objects or nullOptional

List of fallback tiers for cascade pricing (max 10 tiers). Each tier contains line items and optional processor route.

setup_preferencesobject or nullOptional

Preferences for payment method setup. Valid in both ‘payment’ and ‘setup’ modes. Contains per-processor setup configuration under ‘processors’ key.

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. Overrides the default descriptor for the charge made from this session, and is copied onto any subscription created from it so renewals inherit it. A suffix longer than the account prefix allows is trimmed to fit (the trimmed value is what this endpoint returns); an invalid suffix is rejected with 422.

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. Example: {“proc_…”: “ACME EVENT 4412”}. The map is copied onto any subscription created from this session. Keys must resolve to supported processors in the account (422 otherwise).

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