Skip to main content
POST
Create Checkout Session

Authorizations

Authorization
string
header
required

Service (M2M) access token issued by POST /auth/token using the client_credentials grant. Required scopes, where known, are listed on each operation below.

Headers

Idempotency-Key
string

Forwarded as the payment provider's request idempotency key. Retried requests with the same key and parameters are deduped by the provider (roughly a 24-hour replay window) instead of creating a second resource. Recommended: an opaque, randomly-generated value such as a UUID rather than a predictable or derived string.

Body

application/json
type
string
required

Session mode: "payment", "setup", or "subscription".

ui_mode
string

One of "embedded", "hosted", "embedded_page", "hosted_page", "elements". Default "embedded". The legacy "embedded"/"hosted" values are translated to the payment provider's current values "embedded_page"/"hosted_page" before the provider call; "elements" passes through unchanged; the response echoes the value you sent.

success_url
string

Required when ui_mode resolves to a hosted page ("hosted" or "hosted_page"). Must be a well-formed http(s) URL — a malformed value or another scheme is rejected with a 400 rather than forwarded to the provider.

return_url
string

Redirect target after completion for embedded checkouts, where it is optional. Required when ui_mode is "elements" — the payment provider rejects the session otherwise. Same http(s) URL check as success_url.

cancel_url
string

Only allowed when ui_mode resolves to a hosted page. Shows a back button on the hosted checkout page and redirects the customer here if they cancel. A non-empty value on "embedded", "embedded_page" or "elements" — including when ui_mode is omitted, which defaults to embedded — is rejected with a 400; a whitespace-only value is treated as absent. Same http(s) URL check as success_url.

customer_data
object

Customer name and email; omit if provider_customer_id provided.

provider_customer_id
string

Existing payment provider customer ID.

currency
string

Required when type is "setup"; ISO 4217 code.

provider_coupon_ids
string[]

Coupon IDs; only for payment and subscription modes. Mutually exclusive with provider_promotion_code_ids.

provider_promotion_code_ids
string[]

Promotion code IDs; only for payment and subscription modes. Mutually exclusive with provider_coupon_ids — providing both is rejected with a 400.

items
object[]

Required for payment and subscription modes. A subscription cart may hold both recurring and one-time prices in one array — no discriminator is needed, each entry is routed by the price's own type, and a one-time amount lands on the subscription's first invoice, charged in full at creation. A subscription cart needs exactly one recurring price, with any number of one-time prices beside it: pause, resume and cancel act on the whole subscription, so create one subscription per recurring product. In a cart of two or more lines, a price unknown to your account is a 404 naming the id; in a one-line cart the payment provider rejects it at session creation.

trial_period_days
integer

Trial length in days; positive integer. Subscription sessions only — sending it on a "payment" or "setup" session is rejected with a 400. The trial defers the recurring charge only: a one-time price in the same cart is still charged immediately. Trial-end behaviour is OpenLoop's policy and has no request field — a trial that ends with no payment method on file cancels the subscription rather than invoicing it.

excluded_payment_method_types
string[]

Payment method types the session must not offer; the account's other enabled methods still show. Values are the payment provider's payment method type names (e.g. card, klarna, affirm, afterpay_clearpay), matched exactly and forwarded unchanged. gopay, paypay, qris, rechnung and shopeepay are not yet accepted. Accepted on every session type. Excluding card also removes the card-based express buttons (Apple Pay, Link); wallets that are their own type, such as amazon_pay and cashapp, stay until excluded themselves. Excluding klarna alone can still leave Klarna available through Link; link is not an accepted value, and Link goes away only when card is excluded. An empty array, null, a non-array, a non-string entry or a value that is not accepted is rejected with a 400, and only the last of these names the value.

provider_payment_method_configuration_id
string

Id of a payment method configuration on your payment provider account. The session offers only the methods that configuration enables; without it the account's default configuration applies. Forwarded unchanged, and may be sent together with excluded_payment_method_types to narrow the configuration further. null, a non-string, or an empty or whitespace-only value is rejected with a 400; an id the payment provider doesn't recognise returns the provider's error as a 400. The payment provider's own eligibility rules still apply on top (for example, Affirm and Afterpay are offered only to buyers in the account's own country); if the restrictions leave nothing to offer, the session is still created with a 200, but its hosted page shows no payment methods.

metadata
object

Custom metadata merged onto the checkout session and the mode-specific sub-object. Distinct from customer_data.metadata, which only affects the customer record. Values must be strings. The source key is reserved. Forwarded to the payment provider and republished in events — do not include PHI or PII.

Response

Success.

data
object
required