Pular para o conteúdo principal
Quando uma renovação é recusada, o pior momento para cobrar de novo é agora — e o segundo pior é nunca. As retentativas automáticas 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.
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.
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. Quando um cartão é removido durante uma recuperação já iniciada, a agenda continua avançando e 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_count e invoice.next_payment_attempt publicam a agenda em tempo real; quando a janela termina, next_payment_attempt volta a null.
  • 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.failed traz em next_payment_attempt a data da próxima tentativa automática, que continua marcada.
  • Uma tentativa recusada emite invoice.payment.failed (com o objeto completo da fatura) e charge.failed com o motivo normalizado. A renovação sem cartão emite apenas o evento da fatura, pois nenhuma charge foi criada. 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 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.
Para acompanhar o resultado agregado — quanto falhou, quanto voltou e por qual caminho — use as métricas de recuperação.