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 e o template atuais da organização. Os métodos, os campos obrigatórios e as condições de parcelamento são os que ficaram guardados quando a sessão foi criada.

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; a marca e o Checkout Builder da organização descrevem 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",
  "...": "demais campos da Checkout Session",
  "checkout_experience": {
    "banner": null,
    "confirmation_message": null,
    "cover_image_url": null,
    "footer_expanded": false,
    "funnel": null,
    "header_shows_logo": true,
    "installment_teaser_mode": "maximum_installment",
    "order_summary_mode": "expanded",
    "product_description_mode": "summary",
    "product_image_mode": "thumbnail",
    "product_subtitle_source": "description",
    "require_billing_address": false,
    "require_document": true,
    "require_phone": false,
    "show_compare_at_amount": false,
    "summary_style": "product",
    "tracking": {
      "destinations": [],
      "mode": "inherit"
    }
  },
  "client_secret": null,
  "composition_revision": 0,
  "expires_at": "2026-08-09T14:00:00Z",
  "mode": "payment",
  "optional_items": [],
  "payment_intent": null,
  "payment_status": "unpaid",
  "status": "open",
  "template": "split",
  "url": "https://pay.chargefy.io/session/cs_Vjjo5tzBzWiX1Q8p"
}

Campo	Responsabilidade
`url`	Abre a página hospedada pronta. Vale em qualquer navegador ou aparelho.
`ui_mode`	Modo de apresentação da sessão. Hoje sempre `hosted`: o comprador paga em `url`.
`id`	Identifica a sessão em consultas server-side, retornos e webhooks — e endereça a `url`.
`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 logo, cores, fonte, tema e cantos da organização.	Marca da organização, lida ao abrir a página.
Template	Usa `minimal`, `booking` ou `subscription`.	Checkout Builder, lido ao abrir a página.
Métodos	Apresenta cartão, Pix e boleto permitidos naquela compra.	Regras guardadas na sessão: padrão do Builder ou `payment_method_types` do create.
Dados do comprador	Aplica o piso obrigatório do método e pode exigir documento, telefone e endereço.	Método + campos do Builder copiados na criação.
Parcelamento	Mostra as parcelas e o acréscimo válidos para aquela compra.	Quem paga o juro e limite do Builder copiados na criação.
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.

A apresentação é lida no carregamento da página: a marca da organização (logo, cores, fonte, tema e cantos), em Configurações → Marca, e a composição do Checkout Builder (template, produto e resumo), em Configurações → Checkout. As regras transacionais — métodos, campos obrigatórios e parcelamento — são congeladas em cada sessão na criação: alterar o Builder vale para as sessões criadas dali em diante, nunca para as já abertas. Veja Configurar sua página de checkout.

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. Dentro de uma sessão open, o comprador tenta quantas vezes precisar sem sair da página. Um cartão recusado devolve o payment_intent para requires_payment_method e a próxima tentativa nasce como uma nova charge no mesmo intent; nenhuma sessão ou intent extra é criada. Enquanto uma tentativa ainda está sendo confirmada, um novo envio é recusado com payment_in_progress e a página hospedada acompanha o resultado sozinha. Sua integração não precisa tratar nada disso: o webhook continua sendo a fonte do desfecho.

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.

A Chargefy persiste e enfileira checkout.session.completed antes de responder ao checkout, mas não aguarda a rede do seu endpoint. Na tela de sucesso, o comprador pode usar Redirecionar agora desde o primeiro momento; sem ação, ele segue para a success_url após 10 segundos. Se seu produto ainda estiver liberando acesso, a página de destino deve consultar seu backend e manter o gate até o fulfillment terminar.

Segurança do fluxo

Proteção	Responsabilidade
API key no backend	Cria e consulta sessões server-side; nunca vai para o navegador.
`url` endereçada pelo `id`	É a credencial da sessão: autoriza somente o runtime daquela compra.
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 usa a apresentação atual da organização e confirma pelas regras guardadas na sessão.
Checkout white-label	Use Chargefy.js, Setup Intents e Payment Intents.	Sua aplicação controla a tela e o lifecycle financeiro diretamente.

Um ui_mode: "embedded" — o checkout da Chargefy renderizado dentro do seu site via SDK, autorizado pelo client_secret da sessão — está a caminho. Até lá, a experiência 100% sua é o caminho white-label acima.

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. A marca da página pode ser a da organização filha ou a da própria plataforma, conforme Marca e domínio próprio da plataforma.

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

Receber pagamentos

Clientes e faturamento

Assinaturas

Operação e pós-pagamento

Marketing e rastreamento

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