O que acontece quando um pagamento falha no Polar

O Polar vende as suas subscrições enquanto merchant of record. Quando uma renovação de subscrição falha, o Polar trata ele próprio da recuperação: volta a tentar o cartão, mantém a subscrição num estado recuperável e revoga os benefícios se nada funcionar. As regras são simples e quase todas fixas, o que é bom saber antes de desenhar o que quer que seja à volta delas.

Este guia explica a sequência passo a passo, a única definição que controla, os webhooks a ouvir e o que pode acrescentar sem lutar contra o fluxo do próprio Polar. Baseia-se na documentação do Polar: recovering failed payments, how subscriptions work, os webhooks subscription.past_due e subscription.revoked (todos consultados em novembro de 2026). Quando as páginas do Polar não concordam ou não dizem nada, assinalamo-lo.

A sequência, passo a passo

Segundo a página sobre pagamentos falhados do Polar:

1. Na renovação, o Polar começa por avançar a subscrição para o ciclo de faturação seguinte e depois tenta cobrar o método de pagamento por omissão do cliente.
2. Se a cobrança falhar, a subscrição não é cancelada. Passa a past_due e entra na recuperação automática de pagamentos do Polar.
3. O Polar volta a tentar o pagamento num calendário fixo: quatro tentativas repartidas por 21 dias, contados a partir da primeira falha. O calendário é definido pelo Polar e não é configurável.
4. Se entretanto o cliente atualizar o método de pagamento, o Polar volta a tentar a cobrança de imediato em vez de esperar pela tentativa agendada seguinte.
5. Se uma nova tentativa tiver sucesso, a subscrição volta a estar regularizada.
6. Se todas as novas tentativas falharem, ou se o código de recusa mostrar que o método de pagamento nunca vai funcionar (o Polar dá lost_card como exemplo), o Polar deixa de tentar e revoga a subscrição e os seus benefícios.

O ponto 6 merece atenção. O Polar não continua a tentar um cartão que não pode funcionar, o que é o comportamento certo, e isso quer dizer que as recusas definitivas terminam muito antes dos 21 dias, a menos que o cliente aja.

A definição que controla: o período de tolerância

Por omissão, o Polar revoga os benefícios de forma estrita. O Polar oferece um período de tolerância ao nível da organização que adia a revogação dos benefícios enquanto uma subscrição está past_due. Define-o em Settings, depois Subscriptions, depois “Grace period for benefit revocation”.

O que o período de tolerância faz e não faz, segundo a documentação do Polar:

	Durante o período de tolerância
Estado da subscrição	Continua past_due
Benefícios do cliente	Mantidos
Calendário de novas tentativas	Sem alterações
Contado a partir de	past_due_at

Portanto, o período de tolerância diz respeito ao acesso, não à cobrança. É uma boa escolha quando os benefícios são coisas de que os clientes dependem no dia a dia (uma chave de licença, o acesso a um repositório privado, um papel no Discord), e perdê-los por causa de um problema temporário do cartão faria o cliente sair de vez.

Como o cliente resolve

A solução para a maioria das recusas definitivas é um novo cartão. A visão geral das subscrições do Polar diz que o Customer Portal permite aos clientes atualizar o método de pagamento, descarregar faturas e cancelar. Como o Polar volta a tentar de imediato após uma atualização do método de pagamento, um cliente que atualiza o cartão recupera a subscrição logo.

A documentação do Polar que verificámos não detalha o conteúdo nem o momento dos emails de notificação enviados aos clientes em caso de falha. Teste em sandbox: provoque uma falha com um cartão de teste e veja o que chega à caixa de entrada do cliente antes de escrever as suas próprias mensagens, para não enviar duplicados.

Os webhooks a ouvir

Evento	Significado
subscription.past_due	Uma renovação falhou. O Polar descreve-o como um estado recuperável: o cliente pode atualizar o método de pagamento para repor a subscrição.
subscription.updated	A subscrição mudou, incluindo quando é recuperada
subscription.revoked	A subscrição foi revogada, porque foi cancelada ou porque as novas tentativas de pagamento se esgotaram

Uma incoerência a prever: a página subscription.revoked do Polar diz que, quando as novas tentativas de pagamento se esgotam, o estado passa a unpaid, enquanto a página sobre pagamentos falhados descreve a subscrição a terminar como cancelada, com os benefícios revogados. Escreva o seu handler para tratar os dois como “deixou de pagar” e registe o estado real que recebe.

Uma configuração prática no Polar

1. Decida o período de tolerância. Se os benefícios fazem parte do trabalho diário, defina um. Se os benefícios forem fáceis de repor, a revogação estrita serve.
2. Trate subscription.past_due na sua app. Mostre um banner com um link para o Customer Portal. Muitos clientes nunca leem os emails de faturação, mas veem o seu produto.
3. Explique o que acontece a seguir. Diga ao cliente que o Polar vai tentar de novo e que atualizar o cartão resolve logo o problema.
4. Trate a revogação com cuidado. Em subscription.revoked, guarde os dados do cliente, explique porque é que o acesso parou e dê um caminho claro de regresso.
5. Registe cada falha. Guarde a subscrição, o montante, a data e o resultado. Ao fim de alguns meses verá quantas se recuperam com uma nova tentativa e quantas só após uma atualização do cartão.
6. Teste com cartões de sandbox. Faça uma recusa temporária, uma recusa definitiva e uma recuperação antes de passar a live.

Como fica a cronologia para um cliente

Juntando as regras do Polar, uma recusa temporária típica decorre assim:

1. Dia da renovação: a cobrança falha, a subscrição passa a past_due e subscription.past_due chega à sua app.
2. Nas três semanas seguintes: o Polar faz as suas novas tentativas agendadas. Se definiu um período de tolerância, o cliente mantém os benefícios durante esse tempo.
3. A qualquer momento nessa janela: o cliente atualiza o cartão no Customer Portal, o Polar volta a tentar de imediato e a subscrição é recuperada.
4. Fim da janela sem sucesso: o Polar revoga a subscrição e subscription.revoked chega à sua app.

Numa recusa definitiva, o passo 2 pode ser totalmente saltado, porque o Polar deixa de tentar um método de pagamento que não pode funcionar. É por isso que o banner na app conta mais nas recusas definitivas: a ação do próprio cliente é o único caminho de regresso, e a janela é curta.

O que o Polar não cobre

A recuperação do Polar é intencionalmente simples. As partes que ficam consigo:

• Contexto. O Polar trata todas as falhas da mesma forma. Uma falha num cliente antigo que usa o produto todos os dias merece uma mensagem diferente da de uma conta inativa.
• Mensagens com a sua voz. Se quer mensagens de recuperação que mencionem o plano, a utilização ou a equipa do cliente, é você que as escreve.
• Medição. Recuperados face a perdidos por mês, por causa. Veja churn involuntário para as definições e modelos de emails de recuperação para ideias de mensagens.
• Prevenção. Os cartões que expiram antes da próxima renovação são previsíveis. Um lembrete antes da renovação evita totalmente a falha; veja cartões a expirar.

Fazer isto com o NoChurn

No Polar, a cobrança dos pagamentos, as novas tentativas e o calendário de 21 dias ficam no Polar enquanto merchant of record; o NoChurn não os altera. Lê as suas subscrições e falhas do Polar, envia emails de recuperação escritos por IA que revê antes do envio e dá a cada cliente um score de churn de 0 a 100, enriquecido com os seus próprios dados enviados pela API. Os cancelamentos têm depois um fluxo de cancelamento e emails de reconquista aos dias 30, 60 e 90. Veja NoChurn + Polar.