Checkout white-label do zero: token, setup intent, preview e payment intent
Guia passo a passo pra montar um checkout 100% seu: tokenizar o cartão, salvar como payment method, mostrar o preço certo antes de cobrar e confirmar o pagamento — com o payload de cada etapa e por que ela existe.
Este guia junta as peças que normalmente aparecem espalhadas: Chargefy.js, token, setup intent, payment preview e payment intent. No fim, você tem um checkout inteiro na sua página, com sua marca — a Chargefy só aparece nas chamadas de API, o comprador nunca sai do seu site.A ideia central, antes de qualquer código: o número do cartão nunca chega no seu backend. Ele nasce e morre no navegador do comprador, vira um token de uso único, e daí em diante seu backend só troca IDs com a Chargefy.
A cobrança em si. Referencia o customer e o payment_method.
Um payment intent é cobrado com um payment_method (pm_*), nunca direto com um token_id. O caminho é sempre token → setup_intent → payment_method → payment_intent.
A ordem é sempre a mesma, uma etapa depois da outra:
Isso expõe um objeto global Chargefy. É a única peça que roda no navegador; todo o resto é chamada de backend.
2
Tokenize o cartão (token)
Por que essa etapa existe: é o que mantém o número do cartão longe do seu servidor. O navegador manda o cartão direto pra Chargefy e recebe de volta um ID sem valor nenhum sozinho — um token de uso único.
const chargefy = Chargefy({ environment: "live" });const token = await chargefy.createPaymentToken({ number: cardNumber, exp_month: expMonth, exp_year: expYear, cvc: cvc, name: holderName,});// token.id (tok_123) é tudo que você manda pro seu backend.await fetch("/api/checkout", { method: "POST", body: JSON.stringify({ token_id: token.id }),});
Em environment: "test" nenhum dado sai pro ar — use um cartão de teste pra simular aprovação e recusa sem precisar de cartão de verdade.
3
Tenha um customer (customer)
Por que essa etapa existe: o cartão salvo pertence a alguém. No Brasil, salvar cartão exige document (CPF/CNPJ) — sem isso o setup intent do próximo passo falha.
Já tem esse comprador cadastrado? Reutilize o customer existente em vez de criar um novo — assim o histórico e os cartões salvos ficam todos no mesmo perfil.
4
Troque o token por um cartão salvo (setup intent)
Por que essa etapa existe: o token do passo 2 morre no primeiro uso. Pra poder cobrar de fato, você precisa de um cartão que sobrevive — é isso que o setup intent devolve. Com confirm: true, você cria e confirma em uma chamada só.
A partir daqui, o que importa é payment_method: "pm_456" — guarde esse ID. É ele que cobra.
5
Exiba o valor exato das parcelas (payment preview)
Por que essa etapa existe: no Brasil, isso é basicamente pra uma coisa só — exibir no seu checkout a quantidade de parcelas e o valor exato de cada uma, já com o acréscimo calculado. Você não calcula juro na mão: manda o valor e a Chargefy devolve a tabela pronta. PIX e boleto vêm no mesmo payload, mas o motivo de esse objeto existir é resolver o parcelamento do cartão.
payment_methods.credit_card.installments.options[] é a tabela de parcelas pronta pro seu select — uma linha por parcela, de 1x até o max_count. count, per_installment_amount e amount_total são exatamente o que aparece na tela.
Se você ligou repasse de taxa (o comprador cobre a sua taxa e você recebe o valor cheio), envie has_surcharge: true. Os totais sobem e surcharge_amount aparece preenchido — veja Repasse de taxa.
Isto é só exibição. Quando o comprador escolher a parcela, você envia essa escolha pro payment intent no próximo passo — e é lá, não aqui, que o valor é travado de verdade.
6
Cobre (payment intent)
Por que essa etapa existe: é a cobrança de fato. Referencia o customer e o payment_method salvos, com o count de parcelas que o comprador escolheu na tela anterior.
amount já vem com os juros embutidos — é o total que saiu do cartão do comprador. status: "succeeded" significa pago; trate failed lendo last_payment_error.
Quer que o comprador cubra a sua taxa também? Envie has_surcharge: true aqui — o mesmo flag que você mandou no preview. A Chargefy recalcula tudo de novo no servidor; o preview nunca é a fonte de verdade da cobrança.
O payment_preview fica de fora dessa corrente de propósito — ele não gera nenhum ID, só monta a lista de parcelas com o juro já calculado. Você chama quantas vezes quiser (a cada vez que o valor mudar, por exemplo com um cupom) sem afetar nada.
