Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

Access token from POST /v1/auth/token, sent as Authorization: Bearer <token>. Treat it as opaque.

Body

application/json

Optional body for creating a checkout session.

Every field is optional. You don't send your merchant ID -- it is taken from your access token.

amount
integer | null

GROSS order total in smallest currency unit (optional; enables amount-conditioned discovery). This is the order value, not necessarily what the card pays -- see net_payable_amount.

Required range: x >= 0
billing
ThreeDsBillingData · object | null

Cardholder billing data for 3-D Secure, kept server-side (encrypted) for this session and sent to the card scheme during 3DS authentication. Never forwarded to tokenization; erased once the authentication completes. Same fields and limits as the billing sent by the 3DS authentication step your payment page / Elements SDK runs.

cancel_url
string | null

Payment-cancel redirect URL. Validated against the merchant's allowed_domains (422 on mismatch).

Maximum string length: 2048
channel
enum<string> | null

The channel this checkout belongs to, for 3DS: send PAYMENT_LINK from a payment-link integration so the acquirer's payment-link 3DS rules apply. Omitted means ECOMMERCE. Fixed at create (not PATCHable); the browser never supplies it.

Available options:
ECOMMERCE,
PAYMENT_LINK
currency
string | null

ISO 4217 currency code. When set, response includes supported payment_methods.

Required string length: 3
Pattern: ^[A-Za-z]{3}$
ip_address
string | null

Your customer's IP address, used as a fraud signal (optional).

Maximum string length: 45
net_payable_amount
integer | null

Minor units the CARD will be charged -- the amount 3DS authenticates. Equal to amount for a plain card sale; the post-redemption residual for a voucher/rewards flow. REQUIRED for any session that will run 3DS: the 3DS authentication step your payment page / Elements SDK runs refuses without it rather than authenticating the gross order amount, which would be the wrong figure.

Required range: x >= 0
outlet_id
string | null

Outlet UUID for discovery. Defaults to the merchant's DEFAULT outlet.

redemption_expected
boolean | null

Whether this checkout may apply a loyalty/voucher redemption. When true, the 3DS authentication step your payment page / Elements SDK runs refuses until you have set net_payable_amount with PATCH /v1/sessions/{id}, so the amount the card is actually charged is what gets authenticated. OPTIONAL and inert when 3DS does not run -- a non-3DS checkout is unaffected whether it is absent, present, or stale.

success_url
string | null

Post-payment redirect URL. Validated against the merchant's allowed_domains (422 on mismatch).

Maximum string length: 2048
ttl_minutes
integer | null

How long the session stays valid, in minutes (5–60). Defaults to 30. The card a shopper enters stays usable for about 30 minutes whatever this value is, so in a longer session a shopper who waits too long before paying is asked to enter the card again.

Required range: 5 <= x <= 60
user_agent
string | null

Your customer's browser User-Agent, used as a fraud signal (optional).

Maximum string length: 512

Response

Successful Response

Standard success envelope. Every successful response has this shape, with the operation's own payload under data.

data
SessionCreatedResponse · object | null

The operation's result. Its shape is documented per operation; omitted on responses that carry no payload.

message
string | null

Optional human-readable note. Omitted from the response when not set, which is the case for every payment operation today. Never parse it.

request_id
string | null

Correlation ID for this HTTP request, for logs and support. Send your own in the X-Request-Id header (letters, digits and hyphens, up to 36 characters -- other characters are stripped) or the gateway generates one. This is NOT the request_id idempotency key you send in a transaction body; the two are unrelated.

status
string
default:ok

Always ok on a successful (2xx) response. Errors use a different body shape entirely (RFC 9457 problem details), so branch on the HTTP status code, not on this field.