POST
Create a hosted or embedded checkout session

Authorizations

x-api-key
string
header
required

Server-side merchant API key. Never expose it in browser code.

Headers

Idempotency-Key
string

Retry-safe key for create operations.

Body

application/json
amountMinor
integer
required
Required range: x >= 1
currency
string
required
Required string length: 3
Example:

"EUR"

mode
enum<string>
default:hosted
Available options:
hosted,
embedded
method
enum<string>

Legacy single-method alias; prefer paymentMethodTypes

Available options:
bank,
card,
apple_pay,
google_pay
paymentMethodTypes
enum<string>[]
Minimum array length: 1
Available options:
bank,
card,
apple_pay,
google_pay
lineItems
object[]
Minimum array length: 1
couponId
string
shippingRateId
string
taxRateIds
string[]
embedded
boolean
default:false

Compatibility alias for mode=embedded

embeddedCss
string

Compatibility CSS field; prefer appearance.customCss

appearance
object
description
string
orderId
string
customerId
string
customerEmail
string<email>
successUrl
string<uri>
failureUrl
string<uri>
cancelUrl
string<uri>
webhookUrl
string<uri>
allowedOrigins
string<uri>[]
subscriptionOnCompletion
boolean
metadata
object

Response

Checkout session created

id
string
required
amountMinor
integer
required
currency
string
required
status
enum<string>
required
Available options:
pending,
confirmed,
failed,
cancelled,
expired
expiresAt
string<date-time>
required
mode
enum<string>
Available options:
hosted,
embedded
method
enum<string>
Available options:
bank,
card,
apple_pay,
google_pay
paymentMethodTypes
string[]
reference
string
checkoutUrl
string<uri>
paymentUrl
string<uri>
embedded
boolean
metadata
object