> ## Documentation Index > Fetch the complete documentation index at: https://docs.chargefy.io/llms.txt > Use this file to discover all available pages before exploring further. # Retentativas inteligentes > Como a agenda de novas tentativas é calculada, executada e encerrada. 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. **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 ### 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: | Retentativa | 1ª | 2ª | 3ª | 4ª | 5ª | 6ª | 7ª | 8ª | | ----------- | --- | --- | --- | --- | --- | --- | ---- | ---- | | Dia | D+1 | D+2 | D+4 | D+5 | D+7 | D+9 | D+12 | D+14 | 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: | Situação | Efeito no contador | | ----------------------------------------------- | -------------------------------------------------------------------------- | | Primeira cobrança da fatura, de qualquer origem | Conta como a 1ª tentativa | | Retentativa automática da agenda | Avança o contador — executada ou não | | Cobrança manual (API, painel, link, portal) | **Não** avança: recupera sem gastar as tentativas automáticas do assinante | 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](/api-reference/charges/failure-codes) 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: | Ação | O que acontece | Quando usar | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- | | **Marcar como não paga** (padrão) | A assinatura vai para `unpaid` e a cobrança automática para. As faturas continuam abertas e cobráveis à mão — pagar qualquer uma reativa a assinatura. | Você quer suspender o serviço, mas deixar a porta aberta para o cliente regularizar. | | **Manter em atraso** | A assinatura permanece `past_due` e os ciclos seguintes continuam gerando faturas; cada nova fatura aberta entra na fila de recuperação, uma por vez. | Você prefere decidir bloqueios no seu produto, sem que o status trave a cobrança. | | **Cancelar a assinatura** | A assinatura é cancelada em definitivo. Faturas abertas permanecem cobráveis manualmente, mas não há reativação — o cliente precisaria assinar de novo. | Modelos em que inadimplência prolongada deve encerrar o contrato. Por ser irreversível, a tela pede confirmação explícita. | ## 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](/payments/revenue-recovery-analytics).