Sessões de checkout

Uma sessão fixa o valor e os limites da integração antes de abrir a interface do pagador.

Criar no backend

POST /v1/checkout-sessions exige checkouts:write e Idempotency-Key.

{
  "integrationId": "ID_DA_INTEGRACAO",
  "amount": "100.00",
  "currency": "BRL",
  "network": "base",
  "mode": "on",
  "parentOrigin": "https://loja.example",
  "externalId": "pedido-1042",
  "prefill": { "email": "cliente@example.com", "document": "52998224725" },
  "expiresIn": 3600
}

amount é uma string decimal, nunca um float: de 0.01 a 10000.00. O servidor persiste centavos inteiros. expiresIn vai de 300 a 86400 segundos. mode aceita on ou off no sandbox; nenhum dos dois movimenta fundos.

Resposta

data contém id, checkoutUrl, expiresAt e environment. A URL inclui um token aleatório no fragmento. Não registre a URL completa em analytics nem a coloque em páginas públicas.

O pré-preenchimento de e-mail e documento fica criptografado no banco e pode ser corrigido pelo pagador. Carteiras nunca são aceitas. A rede inicial precisa estar na integração; o pagador pode escolher apenas outras redes permitidas.

Consultar

GET /v1/checkout-sessions/:id exige checkouts:read. Retorna metadados e estado, sem token de cliente nem dados pessoais do pagador. A resposta de outra organização é 404.

No navegador, as rotas /v1/public/checkouts/:id usam a capacidade Checkout, com expiração e escopo restritos. Não use sua chave de backend nessas rotas.