Como o checkout funciona

O checkout conecta o que será vendido, a página apresentada ao comprador e o resultado financeiro da tentativa. Na experiência hospedada, sua aplicação cria uma Checkout Session e a Chargefy cuida da coleta e da confirmação; seu backend acompanha o resultado por webhook.

Uma Checkout Session representa uma tentativa de compra. Ela não substitui o Payment Intent, a invoice ou a subscription que registram o resultado financeiro e a recorrência.

O lifecycle do checkout hospedado

Sua aplicação inicia a compra

O backend cria uma Checkout Session com os itens, URLs de retorno e dados opcionais do customer. Se a oferta vem de um Payment Link, cada acesso ao link cria uma sessão nova automaticamente.

A Chargefy abre a página

A resposta contém uma url. Ao redirecionar o navegador, a página carrega a identidade, o template, os métodos e as regras atuais do Checkout Builder da sua organização.

O comprador conclui o formulário

A página coleta os dados exigidos pelo método escolhido, tokeniza o cartão no navegador e permite corrigir recusas ou campos inválidos sem expor sua API key.

A Chargefy coordena o pagamento

Cartão normalmente é confirmado na hora. Pix e boleto entregam os dados de pagamento e aguardam compensação. Em uma venda recorrente, a confirmação também materializa a subscription e a invoice quando aplicável.

Seu backend conclui o pedido

Webhooks informam o estado confiável da sessão. Seu sistema deduplica o evento, confirma o resultado financeiro e só então libera produto, reserva ou acesso.

Página de checkout hospedada pela Chargefy com resumo do pedido, cartão, Pix e boleto — Página hospedada com resumo do pedido, dados do comprador e métodos de pagamento.

A Checkout Session é o contrato da página

Seu backend descreve a compra; o Checkout Builder descreve a experiência. O request não transporta cores, fonte ou layout.

curl -X POST "https://api.chargefy.io/v1/checkout-sessions" \
  -H "Authorization: Bearer {{API_KEY}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: checkout-order-8f4c2a" \
  -d '{
    "cancel_url": "https://meusite.com/carrinho",
    "line_items": [
      {
        "price_data": {
          "currency": "brl",
          "product_data": {
            "name": "Curso de fotografia"
          },
          "unit_amount": 19990
        },
        "quantity": 1
      }
    ],
    "metadata": {},
    "success_url": "https://meusite.com/pedido/confirmado?session_id={CHECKOUT_SESSION_ID}"
  }'

A resposta é o objeto completo da sessão. Estes são os campos que conectam o backend ao navegador:

{
  "id": "cs_Vjjo5tzBzWiX1Q8p",
  "object": "checkout.session",
  "client_secret": "51b88af0b70a6af4a45e6ef221d7078ad79629d66048639a04c70d90aaeef29c",
  "expires_at": "2026-08-09T14:00:00Z",
  "mode": "payment",
  "payment_status": "unpaid",
  "status": "open",
  "url": "https://pay.chargefy.io/session/9f4c2a1b8e3d7f06a5c4b2e1d8f3a6b09c5e2a1f4b7d8c3e6a9f1d2c4b5e8a0f",
  "...": "demais campos da Checkout Session"
}

Campo	Responsabilidade
`url`	Abre a página hospedada pronta.
`client_secret`	Autoriza o runtime do navegador a consultar e confirmar a sessão sem receber sua API key.
`id`	Identifica a sessão em consultas server-side, retornos e webhooks.
`expires_at`	Marca até quando aquela tentativa pode ser aberta e confirmada.
URLs de retorno	`success_url` conclui a navegação; `cancel_url` leva o comprador de volta ao seu site.

O header Idempotency-Key evita criar mais de uma sessão quando sua rota recebe o mesmo pedido novamente por timeout ou retry.

Como os objetos se encaixam

Objeto	Quando participa	O que representa
Product e Price	Antes da sessão, se você usa catálogo	O que é vendido e como o valor é cobrado. Itens ad-hoc também são aceitos.
Checkout Session	Do início ao fim da tentativa	Itens, comprador, URLs, expiração, estado da página e resultado refletido.
Customer	Resolvido na confirmação	A pessoa vinculada à compra e, quando aplicável, ao método reutilizável.
Payment Intent	Na confirmação, quando existe cobrança	O lifecycle financeiro do pagamento.
Invoice e Subscription	Em checkout recorrente	A cobrança operacional e o contrato de recorrência materializados quando aplicável.
Evento de webhook	Depois de cada transição relevante	O aviso assinado que seu backend usa para reagir ao resultado.

A Checkout Session organiza a tentativa, mas não é o livro-razão do pagamento. Para conciliação, combine payment_status, o Payment Intent relacionado, a invoice quando existir e os eventos recebidos.

O que a página resolve

Área	Como funciona	Onde você controla
Layout responsivo	Organiza resumo e formulário para desktop e mobile.	Automático.
Identidade	Aplica cores, fonte, tema e cantos da organização.	Checkout Builder.
Template	Usa `minimal`, `booking` ou `subscription`.	Checkout Builder.
Métodos	Apresenta cartão, Pix e boleto quando habilitados.	Checkout Builder.
Dados do comprador	Aplica o piso obrigatório do método e pode exigir documento, telefone e endereço.	Método + Checkout Builder.
Parcelamento	Mostra de 1 a 12 parcelas e o acréscimo quando configurado.	Checkout Builder.
Descontos	Exibe o campo de cupom quando a sessão permite e aplica descontos válidos.	`allow_discount_codes` da sessão + dados da compra.
Quantidade	Pode permitir que o comprador ajuste a quantidade dentro de uma faixa.	`line_items[].adjustable_quantity`.
Chamada de ação	Mostra “Pagar”, “Assinar”, “Reservar” ou “Doar”.	`submit_type` da sessão.
Pós-compra	Redireciona, inicia um funil de upsell ou encerra a experiência.	URLs da sessão e configuração do funil.

As configurações do Checkout Builder pertencem à organização e são lidas no carregamento da página. Se você alterar um método ou campo obrigatório, a nova regra vale no próximo carregamento, inclusive para sessões já criadas.

Pagamento único e assinatura

O mode é derivado dos itens. Você não o envia no request.

Itens da sessão	`mode`	Resultado da confirmação
Todos com preço `one_time`	`payment`	Uma cobrança é processada e a sessão termina.
Todos com preço recorrente	`subscription`	A subscription é criada com sua cobrança inicial ou trial.
Recorrentes com trial e `payment_method_collection: "if_required"`	`subscription`	Pode concluir sem cobrança nem cartão quando nada é devido hoje.

Uma sessão não aceita misturar itens recorrentes e avulsos. Modele todos os itens como one_time ou todos como recorrentes; uma combinação mista retorna 400.

Em assinaturas, subscription_data pode definir trial, data de encerramento e o comportamento quando o trial termina sem método de pagamento. O cartão coletado fica associado ao customer para as próximas cobranças quando a assinatura precisa dele. Para apenas salvar um cartão sem cobrar, use um Setup Intent, não uma Checkout Session de pagamento.

Customer e dados do comprador

Entrada na criação	O que aparece na página	O que acontece na confirmação
`customer` existente	E-mail preenchido e travado para aquele cadastro.	A sessão permanece ligada ao customer informado.
E-mail ou documento, sem `customer`	Campos pré-preenchidos e editáveis.	A Chargefy procura um customer da organização pelo documento e depois pelo e-mail.
Nenhum dado	Checkout de convidado, com campos vazios.	Um customer existente é reutilizado ou um novo é criado com os dados finais.

A resolução acontece dentro da mesma organização e do mesmo ambiente. A Chargefy não usa metadata para decidir identidade; esse objeto continua opcional, livre e controlado pela sua aplicação.

Cartão, Pix e boleto não terminam ao mesmo tempo

Método	Ao concluir a página	Quando liberar o pedido
Cartão	A autorização normalmente retorna na hora.	Quando `payment_status` estiver `paid` no evento processado.
Pix	A sessão entrega QR Code e fica aguardando pagamento.	No `checkout.session.async.payment.succeeded`.
Boleto	A sessão entrega PDF, código de barras e linha digitável.	No `checkout.session.async.payment.succeeded`, depois da compensação.

Por isso, a sessão separa o estado da página do estado do dinheiro:

Combinação	Significado	Ação recomendada
`open` + `unpaid`	O comprador ainda não terminou.	Aguarde ou expire a tentativa.
`complete` + `paid`	A página terminou e o pagamento foi confirmado.	Execute o fulfillment uma única vez.
`complete` + `unpaid`	O comprador terminou, mas Pix ou boleto ainda não compensou.	Mostre “aguardando pagamento” e espere o evento assíncrono.
`complete` + `no_payment_required`	Um trial de assinatura foi concluído sem cobrança.	Ative conforme o estado da subscription.
`expired` + `unpaid`	A janela da sessão terminou sem confirmação financeira.	Encerre a tentativa e crie outra se o comprador quiser tentar novamente.

Expiração e novas tentativas

Toda Checkout Session nasce com validade fixa de 24 horas. Você também pode expirar uma sessão aberta antes desse prazo. Uma sessão complete ou expired é terminal: não volta a open. Para uma nova tentativa, crie outra sessão. Use um identificador do seu sistema em metadata para correlacionar sessões diferentes ao mesmo carrinho ou pedido, sem tornar nenhuma chave específica obrigatória.

Conclua a transação pelo webhook

Evento	O que significa	Uso típico
`checkout.session.completed`	O comprador concluiu a página.	Entregue cartão pago; para Pix e boleto, registre que a compensação está pendente.
`checkout.session.async.payment.succeeded`	O pagamento assíncrono foi confirmado.	Libere o pedido de Pix ou boleto.
`checkout.session.async.payment.failed`	O pagamento assíncrono falhou ou expirou.	Encerre a tentativa sem entregar.
`checkout.session.expired`	A sessão aberta completou 24 horas sem confirmação.	Libere reserva de estoque ou descarte a tentativa.

A success_url melhora a experiência do comprador, mas não comprova pagamento. Seu backend deve verificar a assinatura do webhook, persistir o event.id com unicidade e confirmar o estado financeiro antes de liberar o pedido.

Quando existe um endpoint inscrito em checkout.session.completed, a Chargefy aguarda um 2xx por até 10 segundos antes do redirect. Se o endpoint demorar ou falhar, o redirect continua; a entrega do webhook será tentada novamente.

Segurança do fluxo

Proteção	Responsabilidade
API key no backend	Cria e consulta sessões server-side; nunca vai para o navegador.
`client_secret` no navegador	Autoriza somente o runtime público daquela sessão.
Tokenização no navegador	Número e CVC do cartão não passam pelo seu servidor.
Idempotência na criação	Evita duplicar a tentativa por retry da sua aplicação.
Webhook assinado	Permite validar origem, deduplicar e processar reentregas.
Objetos financeiros relacionados	Permitem reconciliar o resultado sem depender da página de sucesso.

Quando a interface precisa ficar no seu produto

Experiência	Como começa	Quem controla a interface
Página hospedada	Redirecione para `checkout_session.url`.	A Chargefy renderiza e confirma usando o Checkout Builder.
Frontend próprio com sessão	Use o `client_secret` para consultar e confirmar a Checkout Session.	Sua aplicação renderiza todos os campos e tokeniza o cartão no navegador.
Checkout white-label direto	Use Chargefy.js, Setup Intents e Payment Intents.	Sua aplicação controla a tela e o lifecycle financeiro diretamente.

O client_secret não renderiza um formulário nem um iframe. Ele é a credencial pública daquela sessão. Se você escolher esse caminho, sua equipe assume a interface, os estados de loading, erro, retry e acessibilidade.

Chargefy for Platforms

Esta seção só se aplica a contas com o produto Chargefy for Platforms habilitado. Nesse produto, uma plataforma opera pagamentos para suas organizações filhas.

O lifecycle não muda. A API key da plataforma envia o header Organization para selecionar a organização filha; produtos, preços e customers da sessão precisam pertencer a ela. A página usa o Checkout Builder dessa organização e o webhook carrega seu ID no campo top-level organization.

Próximos passos

Criar a primeira página

Implemente o fluxo hospedado do backend ao webhook.

Entender Checkout Sessions

Aprofunde itens, customers, expiração, métodos, estados e eventos.

Após receber com um Checkout

Conecte retorno, webhook, worker e reconciliação.

Criar um checkout white-label

Construa a interface dentro do seu produto com tokenização no navegador.

Pagamentos online

Integrações avançadas

Payment Intents e cobranças

Formas de pagamento

Customers

Faturas

Assinaturas

Operação financeira

Como o checkout funciona

O lifecycle do checkout hospedado

A Checkout Session é o contrato da página

Como os objetos se encaixam

O que a página resolve

Pagamento único e assinatura

Customer e dados do comprador

Cartão, Pix e boleto não terminam ao mesmo tempo

Expiração e novas tentativas

Conclua a transação pelo webhook

Segurança do fluxo

Quando a interface precisa ficar no seu produto

Chargefy for Platforms

Próximos passos

Criar a primeira página

Entender Checkout Sessions

Após receber com um Checkout

Criar um checkout white-label

​O lifecycle do checkout hospedado

​A Checkout Session é o contrato da página

​Como os objetos se encaixam

​O que a página resolve

​Pagamento único e assinatura

​Customer e dados do comprador

​Cartão, Pix e boleto não terminam ao mesmo tempo

​Expiração e novas tentativas

​Conclua a transação pelo webhook

​Segurança do fluxo

​Quando a interface precisa ficar no seu produto

​Chargefy for Platforms

​Próximos passos

Criar a primeira página

Entender Checkout Sessions

Após receber com um Checkout

Criar um checkout white-label

O lifecycle do checkout hospedado

A Checkout Session é o contrato da página

Como os objetos se encaixam

O que a página resolve

Pagamento único e assinatura

Customer e dados do comprador

Cartão, Pix e boleto não terminam ao mesmo tempo

Expiração e novas tentativas

Conclua a transação pelo webhook

Segurança do fluxo

Quando a interface precisa ficar no seu produto

Chargefy for Platforms

Próximos passos