Checkout sessions

A session fixes the amount and integration limits before the payer interface opens.

Create from your backend

POST /v1/checkout-sessions requires checkouts:write and Idempotency-Key.

{
  "integrationId": "INTEGRATION_ID",
  "amount": "100.00",
  "currency": "BRL",
  "network": "base",
  "mode": "on",
  "parentOrigin": "https://store.example",
  "externalId": "order-1042",
  "prefill": { "email": "customer@example.com", "document": "52998224725" },
  "expiresIn": 3600
}

amount is a decimal string, never a float: 0.01–10000.00. The server persists integer cents. expiresIn supports 300–86400 seconds. Sandbox mode accepts on or off; neither moves funds.

Response

data includes id, checkoutUrl, expiresAt, and environment. The URL includes a random capability in its fragment. Do not log complete URLs to analytics or publish them on public pages.

Prefilled email and document are encrypted in the database and may be corrected by the payer. Wallets are never accepted. The initial network must belong to the integration; only other allowed networks can be selected.

Retrieve

GET /v1/checkout-sessions/:id requires checkouts:read. It returns metadata and state without the client token or payer personal data. Requests for another workspace return 404.

Browser /v1/public/checkouts/:id routes use the scoped, expiring Checkout capability. Never send a backend API key to these routes.