Checkout Sessions

Uma Checkout Session representa uma tentativa individual de compra. Ela reúne os itens, os valores, o comprador, as regras comerciais e o estado daquela experiência de pagamento — do momento em que a página é aberta até a conclusão ou a expiração. Cada sessão é descartável. Ela nasce para uma compra específica, expira em 24 horas e não volta a ficar aberta depois de concluída ou expirada.

​

O que pertence a uma sessão

A Checkout Session funciona como o contexto da compra. Ela mantém juntos os dados que precisam acompanhar aquela tentativa: A sessão coordena a experiência, mas não substitui os objetos financeiros. O Payment Intent controla a cobrança; uma Charge representa cada tentativa de mover dinheiro; invoices e subscriptions entram no fluxo quando a venda exige faturamento ou recorrência.

​

Quando uma Checkout Session é criada

Hoje existem duas origens: Essa diferença evita misturar uma tentativa de compra com uma cobrança já formalizada. Para cobrar uma invoice existente, compartilhe a hosted_invoice_url; para iniciar uma compra nova, use uma Checkout Session ou um Link de pagamento.

​

Checkout Session ou Link de pagamento

Veja Link de pagamento vs. Sessão de checkout para escolher o recurso certo antes de integrar.

​

O que você pode personalizar

Parte da experiência pertence à tentativa de compra; outra parte pertence à organização e é reutilizada em todos os checkouts.

​

Por sessão

O mode não é enviado. A Chargefy o deriva dos itens: preços avulsos criam uma sessão payment; preços recorrentes criam uma sessão subscription. Itens principais avulsos e recorrentes não podem ser misturados em line_items. Order bumps em optional_items são sempre avulsos e podem acompanhar assinaturas, inclusive durante o trial; nesse caso, somente o extra é cobrado hoje.

​

Padrões da organização e regras da sessão

A marca e o Checkout Builder são a configuração compartilhada da organização, mas nem tudo se comporta da mesma forma depois que uma sessão é criada: Assim, a identidade visual pode evoluir sem recriar sessões, enquanto as regras que afetam a escolha e o valor pago pelo comprador permanecem estáveis. A aceitação de códigos de desconto não vem do Builder: ela pertence à sessão em allow_discount_codes ou é herdada do Payment Link que a criou.

​

Como o comprador acessa

A resposta de criação traz url, a página hospedada e pronta para aquela compra. Redirecione o navegador do comprador para esse endereço. A url é a credencial da sessão: quem tem o endereço acompanha e conclui aquela compra, em qualquer navegador ou aparelho. Para uma experiência de pagamento 100% sua, use Payment Intents — a Checkout Session é o caminho da página hospedada.

​

Estados e resultado financeiro

A sessão acompanha dois eixos independentes: Uma sessão de Pix ou boleto pode ficar complete e unpaid: o comprador terminou o formulário, mas o pagamento ainda aguarda compensação. Por isso, chegar à página de sucesso não é prova de pagamento. Use webhooks assinados para liberar produto, ativar acesso e reconciliar a compra. A presença do comprador no frontend nunca substitui essa confirmação.

​

Vantagens da Checkout Session

• isola cada pedido em uma tentativa com valores e comprador próprios;
• entrega uma página hospedada sem exigir que você construa o formulário;
• usa o Checkout Builder como padrão para sessões novas, sem mudar as regras de uma compra que já começou;
• coordena pagamentos avulsos, assinaturas, descontos, parcelamento e dados do comprador;
• mantém API key e decisões comerciais no backend;
• oferece webhooks, client_reference_id e metadata para reconciliação confiável.

​

Próximos passos