Create Checkout Session
Creates a checkout session. For hosted integrations (integrationType: hosted) the
response includes a signed hosted-checkout paymentLink; direct integrations receive
identifiers only — no paymentLink — and initiate the payment against the returned
sessionId via POST /payment.
Request
Your reference for the checkout session. Unique per merchant — reusing a
reference is rejected with 409 DUPLICATE_REFERENCE carrying the existing
session's id. Use a unique value per logical order; retrying a request with the
same reference is a safe probe for whether the original creation succeeded.
Always supply a non-empty value: an empty string is accepted, but it is exempt
from the uniqueness check and the session cannot be found via Search Payments.
See the Payment Status & Recovery guide.
Amount in minor units, denominated in currency (the initiation currency).
Currency of the session (ISO 4217). Without a rateLockId this is the
collection currency the payer pays in. With a rateLockId it must equal the
lock's base currency (the currency you price in, e.g. USD); the payer is then
charged the equivalent in the lock's quote currency at the lock's all-in rate.
Optional. The collection currency — the currency the payer is actually charged in. Defaults to the primary currency for payerDetails.location when omitted. When collectionCurrency differs from currency, Adaptive Currency Conversion applies: priced by the supplied rateLockId, or by its default per-session quote minted at session creation.
Optional rate lock to apply to this session. When set, the session currency
must equal the lock's base currency, the session's collection currency must equal
the lock's quote currency, and the payer is charged the equivalent in the lock's
quote currency at the lock's all-in rate. The lock is verified at session creation
and again when a payment is initiated; a lock that is unknown, expired, or
cancelled is rejected with 422. If omitted and collectionCurrency differs from currency, the conversion falls back to Adaptive Currency Conversion's default per-session rate.
Optional session attributes to pass through the payment lifecycle. All values must be strings. Three keys are meaningful to the hosted checkout — showChargedAs, showConversionRate and showConversionFee — each defaulting to shown and accepting "false" to hide that line from the payer.
Optional session lifetime in seconds (30 seconds to 7 days). The payment confirmation window expires this long after creation; defaults to the standard session lifetime when omitted.
Response
Session created successfully.
When the session was priced by a rate lock, the response also carries
fxCommit — the collection currency and amount the payer will be charged, the all-in
rate, the markup, and the fee — so you can show the payer both amounts without a second
call. A session priced by the default per-session rate returns identifiers only; read it
back with Get Checkout Session to see its fxCommit.
The hosted checkout URL for this session, present when integrationType is hosted. Redirect the buyer to it exactly as returned — the signature query parameter authorises the session, so a URL rebuilt by hand will not authenticate.
Persistent identifier for the payer (customer). CrissCross assigns one when the session is created, or returns the existing payerId if you supplied one in payerDetails.payerId. Store it against your customer record to recognise this customer on future sessions. See the Payer ID guide.
HMAC that authorises this session on the hosted checkout. It is already appended to paymentLink as a signature query parameter, so for a hosted integration you do not need to handle it separately — redirect the buyer to paymentLink as returned. Treat it as a capability for this one session: anyone holding it can act on the session, so do not log it or expose it beyond the buyer's browser. Unrelated to the svix-signature header used to verify webhooks.
Present when the session was priced by a rate lock (rateLockId supplied): the collection currency and amount the payer will be charged at the lock's allInRate, with pricingModel: RATE_LOCK and quoteId the rlk_ lock id. Absent for same-currency sessions and for sessions priced by the default per-session rate.