Como configurar o dunning no Recurly
Como o Recurly trata os pagamentos falhados: campanhas e ciclos de dunning, Intelligent Retries, emails, faturas em atraso e falhadas, faturação e webhooks.
Por Florian
O Recurly tem uma das configurações nativas de dunning mais completas entre as plataformas de faturação de subscrições. As novas tentativas, os emails, as ações no fim do ciclo e as páginas de faturação para os clientes estão todos incorporados, e a maior parte do trabalho é escolher definições sensatas e ligar os webhooks certos à sua app. Este guia percorre cada peça e dá-lhe uma checklist de configuração que pode aplicar hoje.
Tudo o que aqui é específico do Recurly vem da documentação do próprio Recurly: Dunning campaigns, Intelligent retries, Static retries, Dunning 101: Understanding dunning windows, Hosted account management e a referência de webhooks (todos consultados em novembro de 2026). O Recurly vende também um produto separado, o Recurly Commerce, com as suas próprias definições de dunning; este guia trata do Recurly Subscriptions.
Como o Recurly divide o trabalho: novas tentativas e dunning
O Recurly trata duas coisas em separado:
- As novas tentativas decidem quando uma cobrança recusada é tentada de novo.
- O dunning decide o que o cliente recebe, durante quanto tempo e o que acontece à fatura e à subscrição no fim.
Ambos correm sobre a mesma fatura ao mesmo tempo, mas configuram-se em sítios diferentes. Ter essa divisão presente torna mais fácil raciocinar sobre o resto das definições.
Novas tentativas: Intelligent Retries e static retries
Intelligent Retries
Segundo a documentação das Intelligent retries, o Recurly usa um modelo de machine learning para escolher quando voltar a tentar os pagamentos recorrentes por cartão recusados. Concentra-se nas recusas temporárias (como os fundos insuficientes). Os limites documentados:
- As novas tentativas param às 20 tentativas de transação no total ou aos 60 dias desde a criação da fatura, o que acontecer primeiro.
- As Intelligent Retries não se aplicam aos métodos de débito direto como o ACH e o SEPA. O Recurly documenta-os à parte em direct debit retries.
- As recusas definitivas são em geral tratadas como finais e não voltam a ser tentadas automaticamente, com algumas exceções documentadas, por exemplo quando o cliente ou o Account Updater alteram os dados de faturação.
Uma coisa a verificar na sua própria conta: uma entrada do changelog do Recurly de agosto de 2026 descreve as recusas temporárias a serem tentadas de novo até 20 vezes por período de 30 dias, para se alinhar com as regras das redes de cartões. Essa formulação difere da janela de 60 dias da página principal, por isso confirme com o Recurly que limite se aplica a si antes de contar com qualquer um.
Static retries
O Recurly documenta também uma opção sem ML, as static retries, guiadas pelos códigos de recusa do gateway e pelos merchant advice codes. Param após 7 recusas de transação, 20 tentativas no total ou 60 dias desde a criação da fatura, o que acontecer primeiro, ou mais cedo se o ciclo de dunning terminar antes.
Seja qual for a lógica que usa, as novas tentativas nunca duram mais do que o ciclo de dunning. Se a sua janela de dunning for curta, também limita as novas tentativas.
Campanhas e ciclos de dunning
Uma campanha de dunning é o conjunto de regras que o Recurly aplica a uma fatura por pagar. Cada site tem uma campanha por omissão e, nos planos elegíveis, pode criar campanhas adicionais e atribuí-las a planos ou contas específicos. A página de dunning campaigns indica que várias campanhas exigem um plano Professional ou Elite. As campanhas estão em Configuration, depois Dunning Management. As definições de dunning têm versões, por isso editar uma campanha não altera as faturas que já estão em dunning.
Cada campanha contém até três tipos de ciclo, cada um com o seu próprio calendário e os seus emails:
| Tipo de ciclo | Aplica-se a | Modelo de email por omissão |
|---|---|---|
| Payment Declined | Faturas cobradas automaticamente que falham | Payment Declined |
| Invoice Past Due | Faturas cobradas manualmente que ultrapassam o prazo de pagamento | Invoice Past Due |
| Post-Trial Payment Declined | Faturas que falham logo após um período experimental gratuito | Post-Trial Payment Declined |
Nas faturas manuais, o período de dunning começa no dia seguinte àquele em que a fatura ultrapassa o prazo de pagamento.
Quanto deve durar um ciclo?
O guia de janelas de dunning do Recurly recomenda:
- Faturação mensal: uma janela de 27 dias, para que o ciclo termine antes da fatura seguinte, mesmo em fevereiro.
- Faturação trimestral e anual: cerca de 60 dias.
- Faturação semanal: 7 dias.
São recomendações, não limites rígidos. A ideia por trás delas é sólida: se um ciclo mensal durar mais de um mês, uma segunda fatura cai em cima da primeira, e passa a perseguir duas faturas por pagar de um cliente que pode nunca voltar.
O que acontece no fim do ciclo
Para cada ciclo, escolhe o que acontece à fatura e à subscrição se o cliente não tiver pago. Por omissão, o Recurly marca a fatura como failed. Também pode fazer expirar a subscrição, mantê-la ativa ou definir que as faturas nunca falham automaticamente, o que as deixa em atraso indefinidamente.
Alguns comportamentos descritos nos artigos de suporte do Recurly que surpreendem muitas equipas:
- O estado da subscrição e o estado da fatura são independentes. Uma subscrição pode estar ativa enquanto a sua fatura está em atraso (artigo de suporte). Baseie também as decisões de acesso na fatura, não apenas na subscrição.
- Marcar uma fatura como falhada não cancela a subscrição. Se quer que a faturação pare, cancele a subscrição à parte (artigo de suporte).
- Cancelar uma subscrição não para o dunning nas faturas em aberto. Use Stop Collection na fatura para isso (artigo de suporte).
- Não há opção nativa de pausa na configuração do dunning.
Emails de dunning
Cada passo de um ciclo pode enviar um email. O Recurly traz modelos base (Payment Declined, Invoice Past Due, Post-Trial Payment Declined e Subscription Expired for Non-Payment) que não podem ser apagados, e pode criar os seus próprios e associá-los aos passos das campanhas.
O email Payment Declined por omissão já leva o cliente à sua página de hosted account management. Cada conta tem dois URLs alojados: um Account Management URL que inicia a sessão do cliente e um Edit Billing Information URL que abre apenas o formulário de faturação. Se alojar a sua própria página de faturação, pode editar o modelo para apontar para lá, usando o hosted login token da conta obtido pela API.
Um plano de emails sensato para uma campanha mensal:
| Dia | Objetivo | |
|---|---|---|
| 0 | Pagamento recusado | Informar, um link claro para atualizar os dados de faturação |
| 3 | Lembrete | Repetir o link, dizer o que acontece a seguir |
| 10 | Lembrete | Curto, mencionar que o acesso está em risco |
| 20 | Último aviso | Dar a data exata em que a subscrição termina |
| Fim | Expirada por falta de pagamento | Confirmar o fim, oferecer um caminho de regresso |
Mantenha cada email curto e centrado no link de faturação. Não repita ao cliente o motivo da recusa em bruto.
As atualizações dos dados de faturação desencadeiam uma nova tentativa imediata
É um dos comportamentos nativos mais úteis. Segundo a documentação do Recurly, quando um cliente atualiza os dados de faturação, o Recurly volta a tentar cobrar todas as faturas em atraso dessa conta. Isto aplica-se também às recusas definitivas: um novo cartão é o único evento que faz valer a pena voltar a tentar uma fatura com recusa definitiva. No débito direto, mudar para uma nova conta bancária repõe o contador de novas tentativas.
Na prática, isto quer dizer que os seus emails de dunning não precisam de um passo “pagar agora” separado. Levar o cliente ao formulário de faturação é todo o trabalho.
Webhooks a ouvir
A referência de webhooks do Recurly e a documentação de dunning listam os eventos que contam durante o dunning. Os que recebe dependem da configuração do seu site:
| Evento | Quando dispara | O que fazer na sua app |
|---|---|---|
failed_payment |
Após cada pagamento falhado | Marcar a conta, mostrar um banner na app |
successful_payment |
Após um pagamento bem-sucedido | Limpar a marca, repor o acesso |
new_dunning_event |
Quando as faturas entram e se mantêm em dunning | Acompanhar o estado de dunning por conta |
charge_invoice.past_due |
Uma fatura de cobrança fica em atraso (sites com faturas de crédito) | Iniciar os seus próprios lembretes, se os tiver |
charge_invoice.failed |
Uma fatura de cobrança falha, diretamente ou no fim do dunning | Decidir sobre o acesso, parar os lembretes |
subscription_expired |
O Recurly faz expirar uma subscrição, incluindo por falta de pagamento | Retirar o acesso |
Os sites sem faturas de crédito recebem antes as notificações de faturas antigas do Recurly, com nomes diferentes. Verifique que conjunto o seu site envia antes de escrever os seus handlers.
Uma checklist de configuração
- Escolha a sua lógica de novas tentativas. Intelligent Retries para a maioria dos negócios com cartões; verifique como é tentado de novo o débito direto se aceitar ACH ou SEPA.
- Defina a duração do ciclo pela frequência de faturação. Parta das recomendações do Recurly de 27 dias (mensal) e 60 dias (anual).
- Escolha de forma deliberada a ação no fim do ciclo. Decida se a subscrição expira ou continua ativa, e se as faturas falham. Escreva-o para que o suporte saiba.
- Escreva os emails. Um link por email, para a página Edit Billing Information ou para o seu próprio formulário de faturação.
- Acrescente uma campanha pós-trial se tiver períodos experimentais gratuitos. A primeira cobrança após um período experimental falha de forma diferente de uma renovação: o cliente nunca lhe pagou.
- Ligue os webhooks. Baseie o acesso no estado da fatura, não apenas no estado da subscrição.
- Acrescente um banner na app para os clientes com sessão iniciada e uma fatura em atraso. Os emails são fáceis de ignorar; o produto não.
- Reveja todos os meses. Veja as faturas que falharam no fim do dunning e os códigos de recusa por trás delas.
Fazer isto com o NoChurn
As novas tentativas e o dunning nativos do Recurly são sólidos, e o NoChurn não os substitui: as novas tentativas, a faturação e a própria cobrança ficam no Recurly. O NoChurn liga-se com uma chave de API do Recurly, segue os webhooks do Recurly e acrescenta emails de recuperação escritos por IA que revê antes do envio, com um link para o cliente atualizar os dados de faturação. Cobre também o que o dunning não cobre: fluxos de cancelamento com motivos e ofertas (um cupão, uma pausa ou uma mudança de plano na subscrição do Recurly) e um botão de cancelamento num clique sempre visível, emails de reconquista aos dias 30, 60 e 90 com base no motivo do cancelamento e um score de churn de 0 a 100. Os chargebacks vêm do gateway que está por trás do Recurly; com o Stripe ou o Braintree, o NoChurn reúne as provas e redige uma resposta para rever. Veja NoChurn + Recurly.