Skip to main content
Quando seu backend cria uma Checkout Session, ele já conhece o pedido, o comprador e a regra de entrega. Depois que o comprador conclui a página, seu trabalho é reunir três caminhos que podem terminar em momentos diferentes:
  • o navegador volta para a success_url;
  • a Chargefy entrega o webhook da sessão;
  • seu backend ativa o produto, registra o pedido ou libera o serviço.
O objetivo deste guia é fazer esses caminhos convergirem para um único pedido e uma única decisão de entrega, mesmo com atraso, repetição ou pagamento assíncrono.
Este artigo é para uma Checkout Session criada pelo seu backend para um pedido específico. Se você compartilha uma URL reutilizável, veja Após receber com um Link de pagamento: cada acesso ao link cria uma sessão diferente.

​
O fluxo depois do checkout

No checkout hospedado, a primeira tentativa de checkout.session.completed é imediata. A Chargefy aguarda um 2xx por até 10 segundos antes de liberar o redirect; se não receber confirmação, redireciona o comprador e mantém o evento na fila para novas tentativas. Por isso, responda 2xx depois de persistir o evento, não depois de concluir todo o trabalho de entrega.

​
1. Ligue a sessão ao pedido

Crie o pedido ou a tentativa local antes de chamar a API. Depois que a Checkout Session for criada, salve o session.id nessa mesma operação de negócio. Você também pode enviar uma referência própria em metadata. Esse objeto é opcional, controlado pelo seu sistema e ecoado nos eventos da sessão. Mesmo usando metadata, mantenha a relação entre pedido e cs_* no seu banco: ela é mais direta para consultas e suporte.
Não procure o pedido por e-mail, valor ou nome do comprador. Esses dados podem se repetir. Use a relação explícita com a Checkout Session.

​
2. Configure a página de retorno

Há duas formas seguras de identificar qual pedido voltou: Com o placeholder:
Com state, gere um valor aleatório no backend, guarde apenas o hash quando possível e defina uma expiração. Não coloque e-mail, CPF, ID de usuário ou outra informação pessoal nesse valor.
O ID da sessão identifica um recurso, mas não autentica o comprador nem prova pagamento. Nunca coloque client_secret ou API key na success_url.
Quando a página abrir, envie o identificador ao seu backend e peça o estado do pedido. A interface não deve consultar a Chargefy diretamente nem liberar acesso com base apenas no parâmetro da URL.

​
3. Escolha o evento que autoriza a entrega

status responde se o checkout foi concluído. payment_status responde se o pagamento foi confirmado. Para Pix e boleto, esses estados mudam em momentos diferentes.
status: "complete" não significa necessariamente payment_status: "paid". Em Pix e boleto, o comprador pode concluir o formulário antes de o dinheiro ser compensado.
Assine seu endpoint nos eventos necessários, valide a assinatura sobre o corpo bruto, persista event.id com unicidade e execute o trabalho demorado fora da resposta. Os detalhes ficam em Entrega de webhooks.

​
4. Traduza o pagamento para estados do seu produto

O frontend entende melhor estados de produto do que estados financeiros. Seu backend pode expor uma resposta simples como: Mantenha pagamento e entrega separados. Um pedido pode estar pago enquanto seu worker ainda provisiona acesso; também pode estar entregue sem cobrança inicial quando um trial válido começa.

​
5. Faça a página consultar o seu backend

A página de retorno deve consultar um endpoint autenticado do seu sistema. Esse endpoint resolve o pedido pelo session_id ou state e devolve apenas o estado necessário para a interface. Um polling curto pode usar intervalos progressivos, por exemplo 1, 2, 3 e 5 segundos. Depois disso, mostre que o processamento continua e ofereça uma forma de atualizar a página. Não transforme ausência de resposta em falha e não envie o comprador automaticamente para criar outra cobrança. Uma mensagem útil é mais clara do que um spinner sem contexto:
Estamos confirmando seu pedido Seu checkout foi concluído. Isso normalmente leva alguns segundos. Você pode manter esta página aberta.
Se o navegador for fechado, o backend continua processando o webhook. A entrega nunca deve depender de a página permanecer aberta.

​
6. Reconcilie atrasos sem duplicar efeitos

Webhook e página de retorno podem encontrar o mesmo pedido ao mesmo tempo. Os dois caminhos devem chamar a mesma operação idempotente. Quando o estado local parecer atrasado, seu backend pode:
  1. consultar GET /v1/checkout-sessions/{id};
  2. comparar status e payment_status com o pedido salvo;
  3. consultar a subscription quando session.subscription estiver preenchido;
  4. chamar a mesma função de entrega usada pelo worker;
  5. devolver o estado local atualizado para a página.
Defina um intervalo mínimo entre reconciliações para não consultar a API em cada rodada do polling.

​
7. Trate assinaturas depois da primeira sessão

Uma Checkout Session recorrente coordena apenas a entrada na assinatura. Depois da conclusão:
  • use session.subscription para relacionar a compra à assinatura criada;
  • libere trial quando a subscription estiver trialing e essa for a regra do produto;
  • acompanhe renovações por invoice.paid;
  • trate falhas e recuperação pelo lifecycle da assinatura, não criando outra Checkout Session a cada ciclo.
Veja Assinaturas para o ciclo recorrente completo.

​
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.
Além do ID da sessão, use o organization do topo do evento para validar qual organização filha é dona do pedido. Nunca localize uma compra apenas pelo cs_* sem confirmar esse vínculo no seu sistema.

​
Checklist de produção

  • O pedido existe antes da criação da Checkout Session.
  • O cs_* retornado fica salvo no pedido.
  • A success_url usa {CHECKOUT_SESSION_ID} ou um state opaco.
  • Nenhuma API key ou client_secret aparece na URL ou no frontend.
  • A página consulta o estado do seu backend, não decide pagamento.
  • paid, unpaid e no_payment_required têm regras diferentes.
  • Pix e boleto aguardam o evento assíncrono de sucesso.
  • O webhook é validado, persistido e deduplicado antes do 2xx.
  • Webhook, polling e retry chamam a mesma entrega idempotente.
  • Uma falha de ativação não cria outra cobrança.
  • Renovações de assinatura usam eventos de invoice.

​
Próximos passos

Criar uma Sessão de checkout

Configure itens, comprador, recorrência e URLs de retorno.

Entregar pedidos

Implemente persistência, idempotência, retry e compensação.

Entrega de webhooks

Valide assinatura, trate reentregas e monitore seu endpoint.

Consultar Checkout Session

Leia o estado atual da tentativa pelo backend.