Skip to content

Checkout Sessions

Create authoritative checkout state on your server, then pass the short-lived reference to Resolve.js. Requires merchant-write OAuth access. See the Checkout SDK guide.

Create a checkout session

Request

Merchant backends submit authoritative checkout data using an OAuth client-credentials bearer with merchant-write permission. API and OAuth access must be enabled for the merchant. Basic authentication, buyer sessions, and read-only credentials cannot issue sessions. The merchant is derived from the credential, never the request body. An identical normalized payload and merchant-scoped idempotency key return the original session and token, including concurrent retries and reordered object keys. A changed payload returns 409. The reference expires five minutes after original issuance; retries never renew it. An unexpired consumed reference retrieves the original linked checkout; it does not create another checkout or fresh buyer-login authority. Optional assertions provision a merchant-specific buyer during issuance; only the separate browser handoff establishes the buyer context. Every buyer assertion requires email OTP before payment unless the same buyer already has a valid fully authenticated Resolve session. Omitting buyer_session_mode, or sending normal or checkout_only, follows this same requirement. Successful verification establishes normal buyer access; successful checkout logs the buyer out. Limited to 60 requests per minute per merchant.

Security
bearerAuth
Headers
Idempotency-Keystring, [ 1 .. 255 ] characters^[\x20-\x7e]+$required

Printable ASCII key, trimmed and scoped to the authenticated merchant. Whitespace-only keys are invalid. Reuse only with the same payload; after expiry use a new key.

resolve-api-versionstring

Select this documented API version; omission uses the merchant configuration.

Value:"v5"
Bodyapplication/jsonrequired
Any of:
checkoutobjectrequired
buyer_session_modestring

Compatibility field, allowed only with buyer_assertion. Every buyer assertion requires email OTP before payment unless the same buyer already has a valid fully authenticated Resolve session. Neither normal, checkout_only nor omission bypasses verification. The field is part of idempotency and cannot be changed during redemption.

Default:"normal"
Enum:"normal""checkout_only"
buyer_assertionobjectwrite-only

Optional merchant-authenticated identity. Email must match checkout.customer.email after normalization. New sessions require authentication within 15 minutes, allowing at most 60 seconds of future clock skew. Use a stable merchant-scoped subject for an authenticated storefront buyer; never assert an unverified checkout email. Resolve provisions or reuses that merchant-specific buyer during issuance. An identical retry preserves the original assertion timestamp; do not regenerate it while retrying.

curl -i -X POST \
  https://docs.resolvepay.com/_mock/merchant-api/openapi/checkout-sessions \
  -H 'Authorization: Bearer <YOUR_JWT_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: string' \
  -H 'resolve-api-version: v5' \
  -d '{
    "checkout": {
      "cart_id": "cart_123",
      "currency": "USD",
      "total_amount": 25,
      "customer": {
        "email": "buyer@example.com"
      },
      "items": [
        {
          "sku": "sku_123",
          "unit_price": 25,
          "quantity": 1
        }
      ],
      "success_url": "https://merchant.example/success",
      "cancel_url": "https://merchant.example/checkout"
    }
  }'

Responses

Session created, or identical unexpired session replayed without extending its expiry.

Headers
Cache-Controlstring
Value:"no-store"
Bodyapplication/json
idstringrequired

Opaque checkout-session ID.

client_tokenstringrequired

Sensitive browser reference signed with dedicated HS256 configuration. Expires five minutes after original issuance; state-backed and redeemable for only one checkout. Contains only iss, aud, sub, jti, iat, exp. No cart, buyer, assertion, or other PII claims. Pass it as SDK session_token; it is not a merchant OAuth token or buyer login credential. Resolve alone signs/verifies it. Never log it, persist it in browser storage, or place it in a URL.

statusstringrequired

New sessions are pending; retries preserve persisted state.

Enum:"pending""consumed"
expires_atstring, (date-time)required

Original expiry in UTC; unchanged by retries.

Response
{ "id": "string", "client_token": "string", "status": "pending", "expires_at": "2019-08-24T14:15:22Z" }