Checkout Session Token

Every continuation call against the /v1/checkouts/* API is authenticated with the session nonce issued at session-create time. Clients send the nonce as the x-checkout-session-token request header, and the billing API matches it against checkout_session.nonce for the session id on the URL.

The session-create endpoint (POST /v1/checkouts/sessions) is the only /v1/checkouts/* route that does not require the header — it issues the nonce.

Capture the nonce

The session-create response returns the nonce as nonce on CheckoutSessionResponseDto. Stash it alongside the session id; you'll need it on every follow-up call for the lifetime of the session.

const res = await fetch(`${billingApiUrl}/v1/checkouts/sessions`, {
  method: 'POST',
  headers: { 'content-type': 'application/json' },
  body: JSON.stringify({
    clientId,
    currency: 'USD',
    products: [{ code: 'pro_plan', totalAmount: 49.99 }],
    account: { userId, email },
    successUrl: '/success',
    cancelUrl: '/cancel',
  }),
});

const { id: sessionId, nonce } = await res.json();

Echo as x-checkout-session-token

Send the nonce as the x-checkout-session-token header on every continuation call. The header value is the raw nonce string — no Bearer prefix, no encoding.

await fetch(`${billingApiUrl}/v1/checkouts/sessions/${sessionId}/process`, {
  method: 'POST',
  headers: {
    'content-type': 'application/json',
    'x-checkout-session-token': nonce,
    'x-user-id': userId,
  },
  body: JSON.stringify({ tokenizedData, accountData }),
});

A missing or mismatched header is rejected with 401 Unauthorized before any business logic runs.

Protected routes

The header is required on every /v1/checkouts/* route below. For routes that include :id, that session id must match the session that issued the nonce.

Lifetime

The nonce is bound to the session row and lives as long as the session does — it does not rotate per request. Persist it next to the session id wherever your client tracks checkout state (component state, sessionStorage, server-side cache) so that downstream calls can read it back.

There is no separate refresh endpoint. If you lose the nonce, the session can no longer be continued and the buyer must restart at session-create.

Errors

In the SDK these surface as FloPayError with type: 'authentication_error' (401) or type: 'api_error' (404). See the Error Handling guide.