Skip to main content
Este guia vende uma anuidade em 12x com taxa de setup e chega à renovação que se cobra sozinha, com as parcelas contratadas e os juros vigentes. O ponto central do modelo: parcelar não transforma a assinatura em doze cobranças mensais. A venda do ciclo é uma única transação pelo total (com os juros do parcelamento somados quando o comprador os paga; a oferta pode atribuí-los à organização, e então o comprador parcela o valor à vista), o limite do cartão é comprometido pelo valor integral, e a recorrência continua anual — o cartão salvo só volta a ser usado na próxima renovação. Quem guarda o quê:
Como nos outros guias, tudo roda em test mode (ch_test_...), sem dinheiro real. Se esta é a sua primeira integração, faça antes o Aceitar o primeiro pagamento. Daqui em diante os exemplos mostram só o payload: o método e a rota ficam no título de cada bloco.

​
Quantas parcelas o plano comporta

Não existe configuração de parcelamento por produto ou por assinatura. Todo preço recorrente com período maior que um mês oferece parcelas automaticamente, e o máximo é o menor entre quatro limites:
O valor usado no último limite é somente o recorrente com desconto — o que volta em toda renovação. Cobranças iniciais como setup entram no valor parcelado da primeira fatura, mas nunca aumentam o máximo. Quando o resultado é menor que 2, a venda é à vista e o objeto não carrega plano de parcelamento (payment_method_options: null).

​
1. Modele o plano e o setup

O plano é um preço recorrente comum; o setup é um preço avulso de outro produto — nunca um atributo do plano. É essa separação que impede o setup de reaparecer nas renovações.
POST /v1/products
POST /v1/products

​
2. Caminho hospedado: o comprador escolhe as parcelas

Crie uma Checkout Session com o plano e o setup no mesmo carrinho. O checkout particiona sozinho: o recorrente vira a assinatura, o avulso entra somente na primeira fatura — a página marca a linha com “Cobrado somente na primeira fatura” e mostra o valor das próximas renovações à parte.
POST /v1/checkout-sessions
O seletor abre em 1x — quando os juros são do comprador, subir de parcela é uma escolha financeira dele; quando são da organização, todas as opções mostram o mesmo total — e lista cada opção com valor da parcela e o total. Ao confirmar, uma única transação leva plano + setup na quantidade escolhida.

​
3. Caminho direto: transmita a escolha feita no seu checkout

Se o comprador escolheu as parcelas na sua própria interface, transmita a condição na criação. Você não define uma política — apenas repassa o que o comprador aceitou, e a Chargefy valida contra a regra única acima.
POST /v1/subscriptions
A resposta conserva a condição contratada — e é o mesmo shape que os eventos subscription.* carregam:
Resposta (recorte)
A primeira fatura conserva o principal, a quantidade de parcelas e quem paga os juros. Cada nova tentativa — automática, de recuperação ou na página da fatura — calcula os juros pela tabela vigente. Uma cobrança já criada mantém seus valores.
GET /v1/invoices/in_hJgPKzC2vRq8sWmA (recorte)
amount_due é o principal — o que quita a fatura e baseia a taxa da Chargefy e, quando houver, a taxa da plataforma. Os juros do parcelamento aparecem no Payment Intent e na Charge (installment_interest_amount, com interest_payer dizendo quem os paga). Quando o comprador paga, eles são somados ao total enviado ao cartão; quando a organização paga, o cartão é cobrado pelo amount_due e os juros são descontados do líquido da organização.

​
4. Com trial: plano e setup esperam juntos

Num plano com trial, a escolha de parcelas acontece na confirmação e o cartão é salvo, mas nada é cobrado no início — nem o setup. A primeira fatura pagável, no fim do trial, cobra plano e setup juntos, na quantidade escolhida. Se a assinatura for cancelada antes disso, o setup pendente é descartado e nunca pode ser capturado por uma fatura posterior.

​
5. Renovação com a tabela vigente

Cada ciclo cria uma fatura e cobra o cartão salvo em uma nova transação integral. A quantidade de parcelas contratada, o principal da fatura e quem paga os juros não mudam por causa de uma troca de tabela. A renovação e cada tentativa realmente nova usam os juros vigentes; repetir o processamento de uma cobrança existente não recalcula o preço. O setup não retorna nos ciclos seguintes. Por exemplo: uma organização passa da tabela 00349 para 00299. Sua próxima renovação usa os juros de 00299, mantendo as 12 parcelas contratadas. A cobrança do ciclo anterior continua com os valores registrados. Acompanhe invoice.paid e invoice.payment_failed para reagir aos ciclos.

​
Quando a criação é recusada

Erros de validação chegam com error.code estável e error.param apontando o campo — trate pelo code, nunca pela mensagem: Duas regras de atualização valem para sempre: payment_settings é somente leitura depois da criação, e uma mudança de itens que deixaria o valor recorrente abaixo de R$ 7,00 por parcela contratada é recusada antes de entrar em vigor.

​
Teste antes de ligar

Em test mode, os cartões determinísticos valem para o fluxo inteiro: aprove a primeira venda em 12x com 4242 4242 4242 4242, force uma recusa com 4000 0000 0000 9995 e confirme que a retentativa preserva as parcelas e usa os juros vigentes. O caminho completo — criação, fatura, recusa, retentativa e renovação — se comporta exatamente como em produção.