> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Novas tentativas de pagamento de assinaturas
> Tente novamente automaticamente pagamentos de renovação de assinatura com falha seguindo uma programação inteligente de intervalos progressivos para recuperar receita sem nenhum trabalho de integração.
As novas tentativas de pagamento repetem automaticamente os pagamentos de **renovação** de assinatura com falha seguindo uma programação de intervalos progressivos. Quando uma nova tentativa é bem-sucedida, a assinatura é reativada automaticamente — sem exigir nenhuma ação do cliente ou trabalho de integração.
## O que são novas tentativas de pagamento?
Quando um pagamento de renovação de assinatura falha, a assinatura é colocada **em espera**. Com as novas tentativas de pagamento habilitadas, Dodo Payments cobra automaticamente o método de pagamento existente do cliente seguindo uma programação inteligente até que o pagamento seja bem-sucedido ou a janela de recuperação seja encerrada.
Isso recupera a receita perdida devido a falhas temporárias — retenções de cartão expirado, fundos insuficientes que são adicionados posteriormente, erros transitórios de rede — sem enviar um e-mail ao cliente ou pedir que ele atualize qualquer informação.
As novas tentativas de pagamento se aplicam somente a pagamentos de **renovação** de assinatura. Os pagamentos iniciais (configuração do mandato), pagamentos únicos, cobranças por alteração de plano e cobranças sob demanda não são repetidos por este recurso.
## Como funcionam as novas tentativas de pagamento
Um pagamento de renovação de assinatura falha e a assinatura passa para o estado `on_hold`.
O código de erro da falha é verificado. **Recusas temporárias** (fundos insuficientes, recusa genérica, erros de processamento ou de rede etc.) podem passar por novas tentativas. **Recusas definitivas** encerram imediatamente a cadeia de novas tentativas, pois repetir a tentativa não mudará o resultado.
Se a recusa puder passar por uma nova tentativa e a janela de recuperação permitir, a próxima tentativa será agendada. As novas tentativas são executadas fora da sessão usando o método de pagamento existente do cliente, seguindo uma programação de intervalos progressivos.
Na primeira nova tentativa bem-sucedida, a assinatura retorna a `active` e a próxima data de cobrança é avançada normalmente. Se a janela for encerrada antes que qualquer nova tentativa seja bem-sucedida, as novas tentativas são interrompidas e a assinatura permanece em espera.
## Configuração das novas tentativas de pagamento
Habilite e configure as novas tentativas de pagamento em **Settings → Recovery** no seu dashboard.
| Configuração | Descrição | Padrão |
| -------------------------- | ---------------------------------------------------------------------------------------------------------- | ------------------- |
| **Enable Payment Retries** | Tenta novamente automaticamente pagamentos de renovação de assinatura com falha para recuperar receita. | Desativado (opt-in) |
| **Recovery window (days)** | Por quanto tempo continuar tentando um pagamento com falha antes de desistir. Deve estar entre **1 e 30**. | 13 |
A **janela de recuperação** é baseada no momento em que a invoice de renovação com falha foi criada. As novas tentativas só são agendadas enquanto o atraso acumulado dos intervalos ainda couber na janela.
## Programação das novas tentativas
Os intervalos entre as novas tentativas aumentam progressivamente. Até **8 tentativas** são realizadas, desde que cada uma delas caiba na sua janela de recuperação:
| Tentativa | Atraso após a tentativa anterior | Tempo aproximado desde a falha |
| --------- | -------------------------------- | ------------------------------ |
| 1 | 12 horas | 12 horas |
| 2 | 24 horas | 36 horas |
| 3 | 48 horas | \~3,5 dias |
| 4 | 72 horas | \~6,5 dias |
| 5 | 96 horas | \~10,5 dias |
| 6 | 120 horas | \~15,5 dias |
| 7 | 7 dias | \~22,5 dias |
| 8 | 7 dias | \~29,5 dias |
Uma janela de recuperação de **13 dias** (o padrão) cobre as tentativas de 1 a 5 (a tentativa 5 ocorre aproximadamente 10,5 dias após a falha). Aumente a janela até o máximo de 30 dias se quiser que as tentativas posteriores e mais espaçadas (6 a 8) sejam executadas.
## Transições de status da assinatura
| Evento | Status da assinatura |
| ------------------------------ | --------------------------------------------------------------------------------------------------- |
| Pagamento de renovação falha | `active` → `on_hold` |
| Nova tentativa falha | permanece em `on_hold` (próxima tentativa agendada se a janela permitir) |
| Nova tentativa é bem-sucedida | `on_hold` → `active`, próxima data de cobrança avançada |
| Janela de recuperação esgotada | permanece em `on_hold` |
| Assinatura cancelada | novas tentativas agendadas são interrompidas imediatamente (terminal — nenhuma tentativa adicional) |
Se uma assinatura for cancelada enquanto ainda houver novas tentativas agendadas, a cadeia de novas tentativas será encerrada imediatamente e nenhuma tentativa adicional será realizada. Outros status não ativos (`on_hold`, `expired`, `pending`, `failed`) continuam passando por novas tentativas, pois suas invoices de renovação em aberto representam uma dívida referente a períodos que o cliente já consumiu.
Essas transições emitem os eventos padrão de webhook de assinatura, para que você possa controlar a lógica de direitos de acesso a partir deles sem nenhum tratamento especial para novas tentativas:
| Evento | Ocorre quando |
| ---------------------- | ------------------------------------------------------------ |
| `subscription.on_hold` | Uma renovação falha e a assinatura é colocada em espera |
| `subscription.active` | Uma nova tentativa é bem-sucedida e a assinatura é reativada |
Veja os schemas completos de payload dos webhooks para eventos do ciclo de vida da assinatura.
## Falhas que podem ou não passar por novas tentativas
| Tipo de falha | Exemplos | Nova tentativa? |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| **Recusa temporária** | Fundos insuficientes, recusa genérica, limite de frequência do cartão excedido, erro de processamento, erro/timeout de rede, tente novamente mais tarde | Sim |
| **Recusa definitiva** | Cartão roubado/perdido, cartão inválido, transação não autorizada pelo emissor, conta encerrada e outras recusas terminais | Não — a cadeia termina imediatamente |
Tentar novamente uma recusa definitiva não mudará o resultado, portanto a cadeia de novas tentativas é encerrada assim que uma recusa definitiva é identificada. Combine as novas tentativas de pagamento com [Subscription Dunning](/features/recovery/subscription-dunning) para solicitar que o cliente atualize o método de pagamento nesses casos.
## Novas tentativas de pagamento vs. dunning
As novas tentativas de pagamento e o [Subscription Dunning](/features/recovery/subscription-dunning) são ferramentas complementares de recuperação:
| | Novas tentativas de pagamento | Subscription Dunning |
| ------------------- | -------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| **Mecanismo** | Faz novas cobranças silenciosamente usando o método de pagamento existente | Envia e-mails ao cliente para que ele atualize o método de pagamento |
| **Ação do cliente** | Nenhuma necessária | O cliente atualiza o método de pagamento no portal |
| **Ideal para** | Recusas temporárias que são resolvidas por conta própria | Cartões expirados ou inválidos que precisam ser substituídos |
Habilitar ambos oferece a maior cobertura de recuperação: as novas tentativas automáticas capturam falhas transitórias, enquanto o dunning recupera clientes cujo método de pagamento realmente precisa ser atualizado.
## Relacionados
Sequências de e-mails que solicitam que os clientes atualizem seu método de pagamento.
Recupere checkouts únicos incompletos ou com falha usando e-mails direcionados.
Entenda os estados de assinatura envolvidos nos fluxos de recuperação.
Reaja aos eventos `subscription.on_hold` e `subscription.active`.