Checkout e cartão transparente

Fluxo

1. Crie o pedido com o total (POST /v1/orders). O valor nunca vem do navegador.
2. Crie a sessão de checkout com as modalidades aceitas e o endereço de retorno da sua loja.

   {
     "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB",
     "allowedModes": [
       "PIX",
       "BOLETO",
       "CARD_INSTALLMENTS"
     ],
     "returnUrl": "https://loja.exemplo.com.br/obrigado",
     "expiresInSeconds": 86400,
     "notifyPayer": true
   }

   {
     "id": "chk_01JDY8E1B2C3D4E5F6G7H8J9KE",
     "url": "https://pay.exemplo.test/c/chk_01JDY8E1B2C3D4E5F6G7H8J9KE#t=token-efemero",
     "expiresAt": "2026-11-14T13:00:00.000Z",
     "orderId": "ord_01JDY8B1B2C3D4E5F6G7H8J9KB"
   }

3. Envie o pagador para url. O link tem um token de alta entropia; a página usa um token efêmero da sessão, nunca a sua chave.
4. Aguarde o webhook. O retorno do navegador para returnUrl não prova pagamento. Libere o produto ao receber order.payment_completed (ou consulte GET /v1/orders/{id} e confira fulfillmentEligible).

Modalidades

Cada modalidade depende das capacidades da conta (GET /v1/accounts/capabilities). Pedir na sessão uma modalidade indisponível para a conta responde 422 MODE_NOT_AVAILABLE, e nada é oferecido ao pagador; Pix financiado responde 422 CAPABILITY_UNAVAILABLE (sem provedor de crédito). Dois cartões, Pix em parcelas e cartão mensal têm guia próprio: Dois cartões e planos. Consulte a referência do checkout para a situação de cada rota.

• returnUrl precisa ser HTTPS (no Sandbox, http://127.0.0.1 e http://localhost também são aceitos para testes locais).
• A sessão vale 1 hora por padrão; expiresInSeconds aceita de 300 (5 minutos) a 86.400 (24 horas). Para uma nova sessão do mesmo pedido, use outra Idempotency-Key (por exemplo, com o número da tentativa): a mesma chave devolve a mesma sessão.

Cartão transparente e 3DS

• O formulário do checkout envia número e código de segurança diretamente ao serviço de captura, que devolve um identificador pm_…. A API pública não aceita dados de cartão.
• O código de segurança nunca é guardado; o identificador do cartão vale para a conta, o cliente e o uso autorizado.
• Quando o emissor pede autenticação, a operação vem com nextAction: "COMPLETE_3DS" e challengeUrl. A página do checkout abre o desafio; o pagamento só conta depois da confirmação do provedor.
• Recusa: nextAction: "UPDATE_PAYMENT_METHOD". O pagador tenta outro cartão; a mensagem é genérica (sem motivo do emissor).

Expiração e pagamento tardio

A sessão expira só localmente: a cobrança já emitida no provedor não é cancelada automaticamente. Um pagamento que chegue depois da expiração é conciliado e gera os eventos normais; trate a liberação do produto pelo pedido, uma vez só.

const sessao = await eclipta.createCheckout({
  orderId: pedido.id,
  allowedModes: ["PIX", "CARD_INSTALLMENTS"],
  returnUrl: "https://loja.exemplo.com.br/obrigado",
});
redirecionar(sessao.url);