Checkout Sessions

A Checkout Session represents one merchant-defined order and one customer payment attempt. It stores the authoritative line items, total, enabled token/network combinations and presentation mode. The merchant can create it directly, or a public Payment Link or Payment Request can create it from a versioned source snapshot.

Create a new session for each attempt. Do not reuse one between customers or orders.

Endpoints

Method	Endpoint	Description
`POST`	`/api/v1/checkout_sessions`	Create a hosted, embedded or custom Checkout Session.
`POST`	`/api/v1/checkout_sessions/:id/confirm`	Select a token and create exact payment instructions.
`GET`	`/api/v1/checkout_sessions/:id`	Retrieve the current state of a Checkout Session.

These endpoints require a server API key with the matching Checkout Session permission. See Authentication.

The Checkout Session object

Identity and mode

Attribute	Type	Description
`id`	string	Unique `chk_test_...` or `chk_live_...` identifier.
`account_id`	string	Merchant account that owns the session.
`ui_mode`	string	`hosted`, `embedded` or `custom`.
`url`	string or null	Hosted redirect URL, embedded checkout URL or null for custom UI.
`allowed_origin`	string or null	Exact origin allowed to mount an embedded session.
`client_secret`	string	Returned only in the create response for an embedded session. Never returned by retrieval.
`csrf_token`	string	Sensitive server-only confirmation credential. Never expose it to the browser.

The embedded client_secret is short-lived and scoped to the session and allowed_origin. Keep it in browser memory and never log it, persist it, send it to analytics or place it in a URL. The CSRF token belongs on the merchant server and must remain bound to the matching session and customer.

Order

Attribute	Type	Description
`amount_subtotal`	string	Decimal subtotal before discounts.
`amount_total`	string	Decimal amount the order requires.
`currency`	string	Order currency. Currently `USD`.
`mode`	string	Checkout mode. Currently `payment`.
`line_items`	array	Server-authored products, quantities and calculated totals.
`supported_tokens`	array	Enabled token/network combinations available to the customer.
`payment_method_configuration`	object or null	Configuration ID and immutable version resolved when the Session was created.
`payment_method_options`	array	Customer-safe capability snapshot, including wallet experiences and availability reasons.
`description`	string or null	Optional merchant description.
`metadata`	object or null	Merchant-authored data used to associate the payment with an order.
`customer_id`	string or null	Optional merchant customer reference.
`customer_email`	string or null	Optional receipt email.
`client_reference_id`	string or null	Merchant correlation value supplied by a public collection flow.

amount_subtotal and amount_total are calculated by Paybytoken from the line items. Do not send either value when creating a session.

Hosted, embedded and custom checkout must render from payment_method_options and supported_tokens, not from current merchant settings. This keeps an open Session stable after an administrator publishes a new Payment Method Configuration.

Source snapshot

Attribute	Type	Description
`payment_link_id`	string or null	Reusable Payment Link that created this attempt.
`payment_link_version`	integer or null	Link version snapshotted for this attempt.
`payment_request_id`	string or null	Receivable that created this attempt.
`payment_request_version`	integer or null	Finalized request version snapshotted for this attempt.
`origin`	object or null	Customer-safe source attribution, when applicable.
`after_completion`	object or null	Completion behavior copied from the source configuration.

A source change never mutates an existing Checkout Session. Use the source and version fields when investigating which terms the customer actually saw.

Payment and lifecycle

Attribute	Type	Description
`payment_intent_id`	string or null	Payment Intent created after the customer confirms a token and network.
`selected_token_id`	string or null	Token selected when payment instructions are confirmed.
`status`	string	`open`, `completed`, `expired` or `canceled`.
`success_url`	string or null	Hosted return destination after successful checkout.
`cancel_url`	string or null	Merchant destination after cancellation.
`expired_at`	timestamp	Time after which the session can no longer be used.
`used_at`	timestamp or null	Time the session was consumed or canceled.
`created_at`	timestamp	Creation time.
`updated_at`	timestamp	Last update time.

The related payment_intent returned by retrieval contains the selected network, token currency, destination and on-chain payment state.

Branding

The branding snapshot keeps a session visually stable if merchant settings change later:

Attribute	Type	Description
`version`	number	Branding schema version.
`display_name`	string	Merchant name shown in checkout.
`logo_url`	string or null	Merchant logo URL.
`brand_color`	string	Merchant/order panel color.
`brand_foreground_color`	string	Automatically selected text color for the brand surface.
`accent_color`	string	Primary checkout action color.
`accent_foreground_color`	string	Automatically selected text color for the accent surface.