> ## Documentation Index > Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt > Use this file to discover all available pages before exploring further. # Como o checkout funciona > Entenda o lifecycle da Checkout Session, o que a Chargefy resolve na página e quando seu backend pode liberar o pedido. 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 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 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. 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. 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. 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 ## 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. ```bash theme={"theme":"css-variables"} 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: ```json theme={"theme":"css-variables"} { "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](/payments/save-card-for-later), 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](/api-reference/checkout-sessions/expire) 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 Implemente o fluxo hospedado do backend ao webhook. Aprofunde itens, customers, expiração, métodos, estados e eventos. Conecte retorno, webhook, worker e reconciliação. Construa a interface dentro do seu produto com tokenização no navegador.