Skip to main content
POST
Error

Authorizations

Authorization
string
header
required

A merchant secret key (sk_…) sent as Authorization: Bearer <key>.

Headers

Idempotency-Key
string

A unique key that makes retries safe: the same key with the same request body returns the original response instead of repeating the operation.

Maximum string length: 255

Path Parameters

id
string
required

The checkout session id (cs_…).

Response

The session after payment intent creation. Contains payment_intent_client_secret.

A checkout session.

id
string
required

Checkout session id (cs_…).

object
enum<string>
required
Available options:
checkout_session
merchant_id
string
required

Merchant id that owns this session (mer_…).

livemode
boolean
required

True for live-mode sessions; false for test-mode.

mode
enum<string>
required

Checkout mode.

Available options:
payment,
subscription,
setup
ui_mode
enum<string>
required

Presentation mode.

Available options:
hosted,
embedded
submit_type
enum<string>
required

Checkout button label mode.

Available options:
auto,
pay,
book,
donate
status
enum<string>
required

open — active, buyer can continue. complete — the hosted payment or subscription activation finished; inspect payment_status and process webhooks. expired — timed out, buyer must start a new session.

Available options:
open,
complete,
expired
payment_status
enum<string>
required

Payment outcome.

Available options:
paid,
unpaid,
no_payment_required
success_url
string | null
required

URL to redirect the buyer after successful payment.

cancel_url
string | null
required

URL to redirect the buyer if they cancel.

locale
string | null
required

Checkout page locale.

customer
string | null
required

Linked customer id (cus_…).

customer_email
string | null
required

Pre-filled email address.

client_reference_id
string | null
required

Merchant-supplied reference id.

line_items
object[]
required

Required line items.

collect_config
object
required

Field-collection requirements for this session.

amount_subtotal
integer<int64>
required

Sum of required line item amounts in minor units.

amount_total
integer<int64>
required

Subtotal plus the amounts of selected optional items in minor units.

currency
string
required

Uppercase three-letter ISO currency code, derived from the first line item.

payment_intent_id
string | null
required

The payment intent created to collect this session (pi_…). Null until the session is confirmed.

expires_at
integer<int64>
required

Unix epoch seconds when this session expires.

metadata
object
required

Custom key-value pairs attached to this session.

created_at
integer<int64>
required

Unix epoch seconds.

updated_at
integer<int64>
required
merchant
object | null

Merchant display details. Present when the session was retrieved from the hosted checkout page context.

client_secret
string

SDK initialization token for embedded mode. Present only on the create response when ui_mode is embedded; absent on all other responses.

optional_items
object[]

Optional upsell items offered on the checkout form. Absent when none were configured.

selected_optional_item_ids
string[]

Ids of optional items the buyer selected. Absent when none are selected.

payment_intent_client_secret
string | null

Payment intent client secret. Present only on the confirm response so the frontend can initialize the card form.

setup_future_usage
enum<string> | null

Set when the merchant enabled saving the payment method. The hosted form shows a save-card checkbox to the buyer.

Available options:
on_session,
off_session
payment_error
object | null

Error returned to the buyer surface after a declined charge attempt. Absent when no decline occurred.

Back-reference to the payment link that spawned this session (pl_…). Absent for API-created sessions.

tokenization
object | null

Card-fields configuration used by Ionic Checkout. Present when the session includes browser tokenization access.

provider
object | null

Card-fields configuration used by Ionic Checkout. No integration action is required.

url
string

Hosted checkout URL (ui_mode: hosted only). Redirect the buyer here to begin payment.

embed_url
string

Embedded checkout iframe URL (ui_mode: embedded only).