Skip to main content
POST
Create a checkout session

Authorizations

Authorization
string
header
required

Secret key, kc_sk_test_... or kc_sk_live_.... Server-side only.

Headers

Idempotency-Key
string
required

Unique key per logical request, reused on retries. 1 to 255 characters.

Required string length: 1 - 255

Body

application/json
amount
integer<int64>
required
Required range: x >= 1
currency
string
required

ISO 4217 currency code, uppercase.

Pattern: ^[A-Z]{3}$
Example:

"EUR"

country
string
required

ISO 3166-1 alpha-2 country code of the shopper.

Pattern: ^[A-Z]{2}$
Example:

"NL"

reference
string
required
Required string length: 1 - 80
return_url
string<uri>
required

HTTPS URL. The shopper returns here with ?session_id=cs_....

description
string
Maximum string length: 500
capture_method
enum<string>
Available options:
automatic,
manual
customer
string

Existing customer ID. Required to store payment methods.

customer_email
string<email>
line_items
object[]
Maximum array length: 100
store_payment_method
boolean

Offer the shopper to save their card for one-click checkout. Requires customer.

locale
string
Example:

"nl-NL"

expires_in
integer
default:3600

Seconds until the session expires.

Required range: 900 <= x <= 86400
metadata
object

Up to 50 keys. Keys up to 40 characters, values up to 500 characters. Echoed back unchanged.

Response

Checkout session created.

id
string
required
Example:

"cs_01JABCDEF"

object
string
required
Allowed value: "checkout_session"
status
enum<string>
required
Available options:
open,
complete,
expired
payment
string
required

ID of the payment created with this session.

amount
integer<int64>
required

Amount in the currency's minor unit.

Required range: x >= 0
currency
string
required

ISO 4217 currency code, uppercase.

Pattern: ^[A-Z]{3}$
Example:

"EUR"

country
string
required

ISO 3166-1 alpha-2 country code of the shopper.

Pattern: ^[A-Z]{2}$
Example:

"NL"

reference
string
required

The partner's order reference.

capture_method
enum<string>
required
Available options:
automatic,
manual
return_url
string<uri>
required
url
string<uri>
required

Hosted checkout URL. Contains the client secret in the URL fragment.

expires_at
string<date-time>
required
created_at
string<date-time>
required
livemode
boolean
required
metadata
object
required

Up to 50 keys. Keys up to 40 characters, values up to 500 characters. Echoed back unchanged.

description
string | null
customer
string | null
customer_email
string | null
line_items
object[]
store_payment_method
boolean
locale
string
Example:

"en-GB"

client_secret
string

Pass to Kalixo.js. Do not log or store it in analytics.

amount_locked
boolean

True once the first payment attempt has started.