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 avulsos e recorrentes não podem ser misturados na mesma sessão.

​

Para toda a organização

O Checkout Builder define a configuração compartilhada pela página hospedada:

• identidade visual, tema, fonte, bordas e template;
• cartão, Pix e boleto disponíveis;
• campos adicionais exigidos do comprador;
• regras de parcelamento;
• exibição do resumo do pedido.

Essas escolhas não são copiadas para o objeto. A página lê a configuração atual da organização quando é aberta, inclusive em sessões que já existiam. A aceitação de códigos de desconto é a exceção: ela é decidida por sessão, pelo campo allow_discount_codes do create (ou herdada do payment link de origem).

​

Como o comprador acessa

A resposta de criação entrega dois identificadores para usos diferentes: Na integração hospedada, normalmente você usa apenas url. Uma experiência própria pode usar client_secret, mas precisa renderizar campos, estados, validações e tokenização de forma segura no navegador.

​

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;
• aplica a mesma configuração de checkout em todos os canais;
• coordena pagamentos avulsos, assinaturas, descontos, parcelamento e dados do comprador;
• mantém API key e decisões comerciais no backend;
• oferece webhooks e metadata para reconciliação confiável.

​

Próximos passos