Como recuperar pagamentos de subscrição falhados no Braintree

A faturação recorrente do Braintree é deliberadamente enxuta. Cobra as subscrições, repete as cobranças falhadas segundo um calendário que escolhe e diz-lhe o que aconteceu através de webhooks. Tudo o resto, incluindo os emails aos clientes, uma página para atualizar o cartão e o que o seu produto faz enquanto uma subscrição está em atraso, fica a seu cargo. Este guia cobre o que o Braintree faz nativamente, as definições que contam e as peças que precisa de acrescentar. Termina com uma secção curta sobre disputas, já que uma renovação falhada ou contestada se transforma muitas vezes numa.

Baseia-se na documentação do próprio Braintree: Recurring billing advanced settings, a Recurring billing overview, Statuses, Subscription: Retry Charge, Subscription webhooks, Account Updater e Managing disputes via the API (todos consultados em novembro de 2026).

O que acontece quando uma cobrança de subscrição falha

Quando o Braintree fatura uma subscrição e a transação é recusada pelo processador ou rejeitada pelo gateway, a subscrição passa para Past Due. A partir daí, segundo o guia de definições avançadas:

• O Braintree tenta de novo automaticamente se as novas tentativas estiverem ativas no Control Panel.
• Uma nova tentativa bem-sucedida devolve a subscrição a Active, desde que não tenha passado a data final de faturação.
• As novas tentativas automáticas não alteram as datas de início e de fim do período de faturação atual.
• Alguns códigos de recusa, como um cartão expirado ou roubado, nunca são repetidos, porque indicam que a transação dificilmente vai ter sucesso.

O objeto subscription ajuda-o a acompanhar isto: daysPastDue dá o número de dias em que a subscrição está em atraso, e failureCount conta as tentativas de cobrança falhadas consecutivas.

Estados de subscrição num relance

Estado	Significado (segundo a referência de estados do Braintree)
Active	Faturação normal
Past Due	Uma cobrança falhou; podem estar pendentes novas tentativas
Canceled	Não haverá mais faturação
Expired	A subscrição atingiu o número de ciclos de faturação definido

Expired não é um estado de falha; uma subscrição que termina por falta de pagamento aparece como Canceled ou fica Past Due, consoante as suas definições.

As definições de novas tentativas

As novas tentativas configuram-se no Control Panel em Account Settings, Recurring Billing, Options, não pela API. As definições documentadas pelo Braintree:

• Se deve repetir automaticamente as transações falhadas.
• Dias antes da primeira nova tentativa, entre 1 e 10 dias.
• O que fazer depois de as novas tentativas falharem: cancelar a subscrição, continuar a tentar ou deixá-la em atraso.

A última definição merece uma escolha ponderada:

Opção	O que o Braintree faz	Quando faz sentido
Cancelar	Termina a subscrição	Quer um estado final claro e vai reconquistar os clientes à parte
Continuar a tentar	Tenta uma vez por ciclo de faturação, na data habitual de faturação	Planos de baixo valor em que os clientes muitas vezes carregam o cartão mais tarde
Deixar em atraso	O saldo continua a acumular a cada ciclo, sem novas tentativas	Vai cobrar por si e precisa do histórico

Com “deixar em atraso”, o saldo cresce a cada ciclo sem nenhuma nova tentativa, por isso alguém tem de contactar o cliente. Com “continuar a tentar”, há apenas uma tentativa por ciclo, por isso não substitui novas tentativas rápidas depois da primeira falha.

Novas tentativas manuais

Pode repetir por si uma subscrição em atraso com o Subscription: Retry Charge, pela API ou pelo Control Panel. Passe true para submeter automaticamente a transação para liquidação se a nova tentativa tiver sucesso. Uma nova tentativa manual bem-sucedida devolve a subscrição a Active; uma nova tentativa manual falhada não conta como uma das tentativas automáticas. É isto que chama logo depois de um cliente atualizar o cartão, em vez de esperar pela próxima tentativa agendada.

Account Updater

O Account Updater pede dados atualizados para cartões guardados no vault que expiraram ou foram substituídos, o que evita algumas falhas antes de acontecerem. Segundo a documentação do Braintree:

• As atualizações dependem da participação do banco emissor; os cartões pré-pagos e os cartões usados através do Apple Pay ou do Google Pay não são suportados.
• Depois do lote inicial, os pedidos são enviados de forma contínua, incluindo quando um pagamento recorrente vence nas duas semanas seguintes, e depois de algumas recusas.
• Pode rever as atualizações no Control Panel, num relatório ou através de um webhook diário.

Um detalhe importante: adicionar um novo método de pagamento ao vault de um cliente não muda as subscrições existentes para ele. Se um cliente lhe der um novo cartão, atualize o token do método de pagamento da subscrição e depois repita a cobrança.

Webhooks para subscrições

O Braintree envia estes tipos de webhook de subscrição:

Tipo	Quando é disparado	O que fazer
subscription_charged_unsuccessfully	Uma subscrição existente não consegue gerar uma cobrança bem-sucedida (não em novas tentativas manuais, não na cobrança inicial)	Registar a recusa, iniciar as mensagens ao cliente
subscription_went_past_due	A subscrição passa de Active para Past Due (uma vez por ciclo)	Mostrar um banner na app, enviar o primeiro email
subscription_charged_successfully	Uma cobrança tem sucesso	Parar as mensagens, retirar o banner
subscription_went_active	A subscrição fica Active	Repor o acesso
subscription_canceled	A subscrição é cancelada	Retirar o acesso, guardar a data de cancelamento
subscription_expired	A subscrição atingiu o último ciclo	Terminar o acesso como previsto

O Braintree nota que a data de cancelamento não é devolvida nos resultados de pesquisa de subscrições, por isso, se precisar dela, guarde-a quando chegar subscription_canceled.

O que precisa de acrescentar por si

O Braintree documenta algumas notificações por email para a faturação recorrente; verifique o que cobrem para a sua conta. Um processo de recuperação completo precisa normalmente de mais do que isso:

1. Um primeiro email em subscription_went_past_due, enviado no mesmo dia, com um único link para atualizar o cartão. Não cite o motivo de recusa em bruto.
2. Uma página de atualização do cartão construída com a integração client-side do Braintree, para que os dados do cartão vão diretamente para o Braintree e nunca passem pelos seus servidores. Em caso de sucesso, atualize o método de pagamento da subscrição e chame o Retry Charge.
3. Lembretes calendarizados à volta das novas tentativas, por exemplo um dia depois de cada tentativa agendada falhar.
4. Um aviso final antes de a subscrição ser cancelada, com a data.
5. Um banner na app enquanto a subscrição estiver em atraso.
6. Tratamento separado para recusas definitivas. Se o cartão estiver expirado ou dado como roubado, o Braintree não vai tentar de novo, por isso o email é o único caminho para a recuperação: envie-o de imediato.

Disputas no Braintree

As disputas são a outra forma de a receita de subscrições se perder, e o Braintree disponibiliza uma API completa para elas, descrita em Managing disputes via the API:

• Webhooks dos tipos dispute_opened, dispute_won, dispute_lost, dispute_accepted, dispute_expired e outros dizem-lhe quando um caso abre ou muda de estado.
• Provas em texto (por exemplo um reembolso ou um número de tracking) adicionam-se com Dispute: Add Text Evidence.
• Provas em ficheiro carregam-se com um pedido Document Upload e depois anexam-se com Dispute: Add File Evidence. A documentação do Braintree indica um limite de 4 MB por ficheiro e 5 MB por disputa, por predefinição.
• Finalize envia a sua resposta e as provas ao banco do titular do cartão. As provas só podem ser adicionadas enquanto a disputa está aberta.
• Data de resposta: cada disputa tem uma. Se a falhar, perde o direito de contestar e a disputa passa a expirada.
• Aceitar uma disputa significa que não a contesta e os fundos voltam para o cliente.

Para um negócio de subscrições, a prova mais forte é normalmente o histórico: quando o cliente se inscreveu, o que usou, que lembretes recebeu e se alguma vez tentou cancelar. Reúna-o antes de o prazo se aproximar.

Fazer isto com o NoChurn

O Braintree fica com o processamento de cartões, a sua conta de comerciante e as suas próprias novas tentativas de subscrição; o NoChurn trabalha ao lado deles. Liga-se com o seu merchant ID e as chaves de API do Braintree, segue os webhooks do Braintree e acrescenta emails de recuperação escritos pela IA que revê antes de serem enviados, com uma página alojada para atualizar o método de pagamento. Para as disputas, o NoChurn reúne provas automaticamente (respostas do fluxo de cancelamento, emails enviados, utilização, conversas de suporte) e redige uma resposta com IA, que só é enviada ao Braintree depois de a rever. Acrescenta também fluxos de cancelamento com ofertas e um cancelamento com um clique sempre visível, emails de reconquista aos 30, 60 e 90 dias e um score de churn de 0 a 100. Veja NoChurn + Braintree.