Create the merchant's checkout session

Create the session on the merchant’s server with POST /api/checkout-sessions. Authenticate with the merchant’s own sk_ key and omit X-Merchant-Id.

Build the body from the merchant’s authoritative order record. Supply the amount, currency, description, line items, order identifier, return locations, and allowed buyer origins that apply to that order. Send Idempotency-Key when a network retry must represent the same creation intent.

Store checkout_session_id beside the merchant’s order. Give the browser only that identifier, checkout_url, or embed_url; never pass it the key that created the session. Look up request and response fields in the shared checkout-session reference or generated operation reference.

Current limits

A checkout session is immutable buyer state, not a cart API. The browser cannot change its amount, currency, merchant, or line items. Create a new session when authoritative order data changes.

Continue to Add the buyer checkout.