Retentativas inteligentes

Quando uma renovação é recusada, o pior momento para cobrar de novo é agora — e o segundo pior é nunca. As retentativas inteligentes ficam no meio-termo certo: uma agenda de novas tentativas concentrada nos primeiros dias após a falha, quando recusas passageiras (saldo, limite) têm mais chance de aprovar, mas com fôlego até o fim da janela para os casos que demoram.

​

Os dois modos de agenda

​

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 janela é teto. Se a combinação não cabe — 8 retentativas em 1 semana, por exemplo — a agenda perde tentativas, nunca dias: viram 7 retentativas, uma por dia. A tela de configuração mostra a lista de datas resultante antes de salvar.

​

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.

O mesmo veto vale para a cobrança manual: depois de uma recusa definitiva, recobrar a fatura com o mesmo cartão — pela API, pelo painel ou pelo link — é recusado com um erro que traz o motivo original da recusa. Um cartão diferente, ou um método novo salvo depois da recusa, passa normalmente. O bloqueio é do cartão vetado, não da fatura. O mesmo compasso de espera vale quando a assinatura não tem forma de pagamento disponível: a agenda avança, next_payment_attempt segue publicado, e a primeira tentativa após o cadastro de um cartão volta a cobrar.

​

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_count e invoice.next_payment_attempt publicam a agenda em tempo real; quando a janela termina, next_payment_attempt volta a null.
• Cada falha emite invoice.payment.failed (com o objeto completo da fatura) e charge.failed com o motivo normalizado; a tentativa que aprova emite charge.succeeded e invoice.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 de política valem para recuperações futuras: uma fatura que já está em recuperação segue a versão da política vigente na primeira falha.

Para acompanhar o resultado agregado — quanto falhou, quanto voltou e por qual caminho — use as métricas de recuperação.