Skip to main content
Este guia vende uma anuidade em 12x com taxa de setup e chega à renovação que se cobra sozinha, na mesma condição, sem novo aceite. 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 pagos pelo comprador), 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 — como os juros são do comprador, subir de parcela é uma escolha dele — e lista cada opção com valor da parcela e total com juros. 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 nasce congelada: quantidade, juros e total ficam gravados nela, e toda tentativa — automática, retentativa da régua ou página hospedada da fatura — cobra exatamente esse valor. Nenhuma mudança posterior na organização altera uma fatura já aberta.
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), somados ao total enviado ao cartã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: a condição se conserva sozinha

A cada ciclo, a renovação cria uma nova fatura, congela a mesma quantidade com a taxa contratada na venda e cobra o cartão salvo em uma nova transação integral. Não há novo aceite nem recálculo: se a organização mudar o máximo de parcelas depois, as assinaturas já contratadas não mudam. O setup não retorna — só as linhas recorrentes. Fique em invoice.paid e invoice.payment_failed para reagir aos ciclos; a régua de retentativas segue a mesma dos outros planos, sempre sobre o valor congelado.

​
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 cobra o mesmo total congelado. O caminho completo — criação, fatura congelada, recusa, retentativa e renovação — se comporta exatamente como em produção.