Como recuperar pagamentos falhados no Chargebee
Como funciona o dunning no Chargebee: modos Smart e Custom, período de dunning, ações finais, emails, links de atualização do cartão e payment_failed.
Por Florian
O Chargebee tem um sistema de dunning maduro: classifica os erros de pagamento, faz novas tentativas segundo o seu próprio calendário ou o seu, envia emails aos clientes com um link para atualizarem o cartão e aplica uma ação final quando nada resulta. A maior parte da recuperação que pode obter do Chargebee resume-se a meia dúzia de definições e à qualidade dos seus emails. Este guia explica essas definições e o que acrescentar à volta delas.
Baseia-se na documentação do próprio Chargebee: Dunning, Smart and manual dunning, What is Smart Dunning, que webhook é disparado durante o dunning, a API de faturas, o evento payment_failed, o Self-Serve Portal e como os clientes atualizam o método de pagamento (todos consultados em novembro de 2026). O Chargebee tem duas gerações de dunning; este guia descreve a atual e assinala onde a versão anterior difere.
Como funciona o dunning no Chargebee
Quando uma cobrança de renovação automática falha, a fatura entra em dunning. O Chargebee faz então novas tentativas de pagamento e envia emails de lembrete durante um período de dunning: o número de dias que a fatura fica em dunning antes de ser executada a ação final. As novas tentativas só acontecem dentro dessa janela.
Com a cobrança automática ativa, a subscrição mantém-se Active durante o dunning. O que acontece depois depende das suas definições.
Dois modos de novas tentativas
A página de Dunning do Chargebee descreve dois modos:
| Modo Smart | Modo Custom | |
|---|---|---|
| Quem escolhe o momento | O Chargebee, com base no erro do gateway | O comerciante, em dias depois da primeira falha |
| Máximo de novas tentativas | Até 12 | Até 5 |
| Recusas definitivas | Não repetidas até o método de pagamento mudar | A documentação descreve novas tentativas nos dias que definir |
| Datas exatas | Não garantidas | Fixas |
O modo Smart classifica os códigos de erro do gateway como recusas definitivas ou temporárias. As recusas definitivas esperam que o cliente atualize o método de pagamento. Para as recusas temporárias, o Chargebee escolhe um momento para tentar de novo com base na categoria do erro e nas probabilidades de recuperação. A documentação do Chargebee diz que as datas exatas das novas tentativas não podem ser garantidas neste modo. Um “Collect Now” manual também conta como nova tentativa. Um artigo de ajuda do Chargebee nota que o Smart Dunning está disponível a partir de planos específicos, por isso verifique o seu.
O modo Custom permite-lhe definir os dias das novas tentativas. O exemplo do Chargebee: com um período de dunning de 8 dias e uma frequência de “1,4,8”, as novas tentativas acontecem 1, 4 e 8 dias depois da primeira falha.
O Chargebee comercializa também o Revive, um modo de novas tentativas com machine learning que funciona dentro dos limites do Smart Dunning. Confirme com o Chargebee a disponibilidade no seu plano.
Falhas de 3D Secure
Seja qual for o modo escolhido, o Chargebee diz que os pagamentos que falharam por causa do 3D Secure só são repetidos no dia anterior ao fim do período de dunning, se o cliente não tiver agido. Esses clientes têm de concluir a autenticação eles próprios, por isso é o email que os recupera, não a nova tentativa.
A ação final
Quando todas as novas tentativas falham, escolhe o que acontece:
- à subscrição: cancelá-la, ou mantê-la ativa;
- à fatura: marcá-la como não paga, anulá-la contabilisticamente (write off) ou invalidá-la (void).
Cancelar é a opção estrita; manter a subscrição ativa com a fatura por pagar dá-lhe mais tempo para chegar ao cliente, à custa de servir alguém que não pagou. Escolha deliberadamente, em vez de deixar a predefinição.
Dunning v1
Sites mais antigos podem ainda estar no Dunning v1. Os próprios artigos de ajuda do Chargebee dão números de novas tentativas diferentes para a v1, por isso, se o seu site a usa, verifique as definições no seu dashboard em vez de confiar num artigo, e pondere passar para a versão atual.
Emails de recuperação e o link de atualização do cartão
O Chargebee envia emails de dunning durante as novas tentativas, e esses emails incluem um link onde o cliente pode atualizar o método de pagamento nas páginas alojadas do Chargebee (guia de atualização do método de pagamento). O Chargebee também pode avisar os clientes quando um cartão está prestes a expirar, expirou ou se tornou inválido.
Há três outras formas de obter um novo método de pagamento:
- Request payment method. A partir da página de um cliente ou de uma subscrição no dashboard, a equipa pode enviar um link seguro para a página alojada do Chargebee.
- Self-Serve Portal. Depois de ativado em Settings › Configure Chargebee › Checkout and Self-Serve Portal, os clientes podem gerir os métodos de pagamento e pagar faturas em dívida (Self-Serve Portal).
- API. A API de hosted pages para gerir fontes de pagamento devolve um URL para onde redireciona o cliente, se quiser o link dentro da sua própria app ou dos seus emails.
Os modelos de email predefinidos são um ponto de partida. Edite-os para que o cliente reconheça a sua marca, perceba o que falhou e veja um único botão claro.
Eventos e webhooks
A orientação do Chargebee para acompanhar o dunning é ouvir o payment_failed e ler o dunning_status da fatura:
dunning_status |
Significado |
|---|---|
in_progress |
A fatura está em dunning, restam novas tentativas |
exhausted |
A última nova tentativa falhou; o período de dunning terminou |
success |
Foi cobrado um pagamento durante o dunning |
stopped |
O dunning foi interrompido para esta fatura |
Cada tentativa falhada durante o dunning gera um evento payment_failed; só o último traz exhausted (que evento marca o fim do dunning). O payment_succeeded é disparado quando um pagamento é cobrado. Use-os para manter os seus próprios registos sincronizados, para parar qualquer comunicação adicional no momento em que um pagamento tem sucesso e para saber quando a ação final aconteceu.
Uma configuração de recuperação, passo a passo
- Escolha um modo de novas tentativas. O modo Smart é a predefinição sensata para pagamentos com cartão se o seu plano o incluir, já que evita novas tentativas inúteis em recusas definitivas. Use o modo Custom se precisar de datas previsíveis, por exemplo para coincidir com o dia em que os seus clientes recebem o salário.
- Defina o período de dunning de acordo com o seu ciclo de faturação. Um plano mensal não pode esperar tanto como um anual.
- Escolha deliberadamente a ação final para a subscrição e para a fatura.
- Ative e reescreva os emails de dunning. Envie o primeiro na primeira falha, com o link de atualização. Nas recusas definitivas, o email é a única coisa que vai recuperar o pagamento.
- Trate o 3D Secure à parte. Diga a esses clientes que o banco precisa que confirmem o pagamento, e envie-lhes o link de imediato.
- Ative o Self-Serve Portal para que os clientes que ignoram o email possam ainda assim corrigir o cartão a partir da sua app.
- Ative os avisos de expiração do cartão para apanhar as falhas antes de acontecerem.
- Ouça
payment_failedepayment_succeedede registe o resultado por tipo de erro, para ver que falhas a sua configuração recupera e quais não.
O que acrescentar por cima
As novas tentativas e os emails do Chargebee cobrem bem o básico. O que deixa a seu cargo é sobretudo a comunicação: emails que soem escritos por uma pessoa, no idioma do cliente, que digam o que fazer para a falha específica; respostas que cheguem a alguém; e um seguimento para os clientes perdidos, para tentar reconquistá-los.
Fazer isto com o NoChurn
O NoChurn liga-se ao seu site Chargebee com uma chave de API e segue os seus webhooks. Funciona ao lado das suas definições de dunning do Chargebee: envia emails de recuperação escritos pela IA, revistos por si, com um link para o cliente atualizar o método de pagamento, e acrescenta fluxos de cancelamento, emails de reconquista aos 30, 60 e 90 dias e um score de churn de 0 a 100. A faturação, a própria cobrança e o seu gateway de pagamento ficam com o Chargebee. As disputas vêm do gateway por trás do Chargebee; com o Stripe ou o Braintree, o NoChurn reúne as provas e redige uma resposta que só é enviada depois de a rever. O NoChurn é grátis abaixo de 300 $ de MRR. Veja NoChurn + Chargebee.