A janela conta a partir da primeira falha — e é cumprida à risca.Todos os passos da agenda são datas absolutas contadas da primeira cobrança
automática que falhou. Uma política de “8 retentativas em 2 semanas” termina em
14 dias, aconteça o que acontecer no meio: tentativa pulada, cobrança manual ou
troca de cartão não esticam o prazo.
Os dois modos de agenda
No painel, acesse Configurações → Assinaturas e faturamento → Assinaturas → Novas tentativas de cobrança. Escolha o agendamento, o número de novas tentativas e o prazo; as datas aparecem antes de salvar.Agenda automática (recomendada)
Você escolhe quantas retentativas (1 a 8) e em qual janela — 1 semana, 2 semanas, 3 semanas, 1 mês ou 2 meses. A Chargefy distribui as tentativas na janela concentrando-as no início, com pelo menos um dia entre uma e outra e nunca além do prazo. Com o padrão de 8 retentativas em 2 semanas, a agenda fica:
Duas regras de sanidade valem sempre:
- Mínimo de um dia entre tentativas. Cobrar o mesmo cartão duas vezes no mesmo dia não melhora a chance de aprovação — e emissores penalizam a repetição.
- A quantidade salva é a quantidade da agenda. Uma semana permite até 7 retentativas; as demais janelas permitem até 8. Ao escolher uma semana, a tela limita a quantidade a 7 e mostra as datas antes de salvar. O servidor também rejeita combinações impossíveis, sem reduzir a agenda depois.
Agenda personalizada
Até 3 retentativas, cada uma definida em dias após a tentativa anterior. Três passos de 3, 5 e 7 dias produzem tentativas em D+3, D+8 e D+15. Use quando a sua operação já tem uma cadência própria — a automática é o melhor ponto de partida para todo o resto.O que conta como tentativa
O contador público da fatura éattempt_count, e ele segue três regras:
A distinção importa na prática: um operador que clica “cobrar” três vezes não
queima a agenda do cliente, e uma retentativa que não pôde executar (veja a
seguir) ainda consome o passo — a janela anda, em vez de esperar para sempre.
Duas garantias de calendário completam a regra:
- A agenda só anda para frente. Cada retentativa é agendada para uma data futura; um passo cujo horário já ficou para trás — por qualquer atraso — não é disparado atrasado nem “recuperado”: a agenda retoma na primeira data ainda à frente. Nunca existem duas cobranças automáticas no mesmo dia.
- Janela vencida é janela encerrada. Se todas as datas da agenda já passaram, não há tentativa de última hora: aplica-se direto a ação final da política. Cobrança manual em uma fatura antiga não “religa” uma agenda que já terminou.
Recusas definitivas: a agenda continua, a cobrança espera
Algumas recusas nenhuma repetição resolve — cartão perdido, roubado, com número incorreto ou exigindo autenticação. O catálogo de motivos de recusa marca quais são. Quando a última falha da fatura é uma delas, a Chargefy não insiste no mesmo cartão:- os passos da agenda continuam sendo agendados e contados normalmente;
- nenhuma cobrança é feita — e nenhum e-mail de falha é enviado — enquanto o assinante não salvar uma forma de pagamento nova;
- assim que um cartão novo aparece, a tentativa seguinte executa com ele;
- se a janela termina antes disso, vale a ação final normal.
next_payment_attempt segue publicado. Os passos sem
cartão não criam cobrança nem e-mail de recusa.
Se a renovação já nasce sem cartão, a assinatura fica em past_due e a
fatura fica open, com attempt_count: 0, next_payment_attempt: null e sem
charge. A integração recebe invoice.payment.failed; se o aviso de falha
estiver ligado, o assinante recebe um e-mail para cadastrar o cartão e pagar
esta fatura. A ausência inicial de cartão não inicia nem esgota uma agenda.
Por exemplo: Maria removeu seu cartão antes da renovação de R$ 99,90 da
Academia Alfa. Ela recebe “Cadastre um cartão para renovar”, abre a fatura pelo
link e paga com o cartão que cadastrar. Só essa cobrança efetivamente
iniciada conta como tentativa.
Uma recuperação por vez, por assinatura
Cada assinatura tem uma recuperação ativa, sempre na fatura mais antiga em aberto. Se um novo ciclo vence no meio de uma recuperação, a fatura nova nasce aberta e aguarda — sem cobrança automática — até a atual terminar. Quando a fatura em recuperação é paga (ou a política manda manter em atraso), a próxima fatura aberta com agenda própria ainda viva assume a recuperação: uma fatura que nunca foi cobrada começa a sua janela na hora, e uma que já esgotou a própria janela é deixada para cobrança manual — herdar a agenda não ressuscita um prazo vencido. Isso evita o pior cenário para o portador: duas agendas paralelas disparando cobranças sobrepostas no mesmo cartão.Quando a janela termina
Se nenhuma tentativa aprovou até o fim da janela, aplica-se a ação final da sua política:O que a sua integração observa
invoice.attempt_counteinvoice.next_payment_attemptpublicam a agenda em tempo real; quando a janela termina,next_payment_attemptvolta anull.- Uma cobrança feita à mão no meio da recuperação — pela API, pelo painel ou
pelo link — não consome passo nem muda a agenda. Se ela for recusada, o
invoice.payment.failedtraz emnext_payment_attempta data da próxima tentativa automática, que continua marcada. - Uma tentativa recusada emite
invoice.payment.failed(com o objeto completo da fatura) echarge.failedcom o motivo normalizado. A renovação sem cartão emite apenas o evento da fatura, pois nenhuma charge foi criada. A tentativa que aprova emitecharge.succeededeinvoice.paid. - As retentativas reutilizam o Payment Intent da fatura — nenhum objeto novo é criado por tentativa, e o histórico de cobranças fica nas charges desse mesmo intent.
- Alterações da agenda e da ação final valem para recuperações futuras: uma fatura em recuperação segue os termos vigentes na primeira falha. Os interruptores de e-mail e o destino do link usam a configuração atual.

