Como gerir pagamentos recorrentes falhados com o Mollie

O Mollie torna os pagamentos recorrentes simples de começar: um primeiro pagamento cria um mandato, e as subscrições ou as cobranças a pedido funcionam com esse mandato. O que acontece quando uma dessas cobranças falha é menos evidente. O Mollie volta a tentar? Quando cancela a subscrição? O que recebe de facto o seu webhook? E como volta a pôr um cliente num método de pagamento que funcione?

Este guia responde a estas perguntas a partir da documentação do próprio Mollie: Recurring payments, Webhooks, Next-gen webhooks, Status reasons, a Chargebacks API, Update subscription e os artigos do centro de ajuda do Mollie sobre pagamentos por Débito Direto SEPA falhados e mandatos após uma devolução (todos consultados em novembro de 2026).

Como funcionam os pagamentos recorrentes do Mollie

O modelo do Mollie tem três peças, descritas no guia de pagamentos recorrentes:

1. Um primeiro pagamento. Cria um pagamento para um cliente com sequenceType definido como first. O cliente conclui-o pelo checkout normal.
2. Um mandato. Quando o primeiro pagamento tem sucesso, o Mollie guarda um mandato para esse cliente e esse método de pagamento. Um mandato não limita o montante nem o número de cobranças.
3. Cobranças recorrentes. Ou cria os pagamentos você mesmo com sequenceType definido como recurring (isto exige um mandato com estado valid), ou cria uma subscrição e o Mollie cobra no intervalo definido. Para as subscrições, o cliente precisa de um mandato no estado pending ou valid.

O cliente só passa pelo checkout uma vez. É a força do modelo e também a razão por que a recuperação é diferente das plataformas com cartão guardado: quando um mandato deixa de funcionar, não há um formulário “atualizar cartão” no próprio mandato. O cliente tem de fazer um novo primeiro pagamento.

O que acontece quando um pagamento de subscrição falha

O Mollie volta a tentar. Segundo o guia de pagamentos recorrentes:

• Se um pagamento de subscrição falhar, o Mollie pode tentá-lo de novo até 5 vezes, uma vez por dia, consoante o motivo da falha.
• O comportamento das novas tentativas pode variar por método de pagamento e por motivo da falha.
• Se uma nova tentativa tiver sucesso, a data da próxima cobrança é atualizada com base no último pagamento bem-sucedido e no seu intervalo.
• Esgotadas todas as novas tentativas, a subscrição é cancelada.

Alguns motivos de falha saem deste padrão. A mesma página lista motivos que cancelam a subscrição de imediato e outros que a cancelam após ocorrências repetidas:

Comportamento	Exemplos de motivos SEPA listados pelo Mollie
Cancelamento imediato	IBAN inválido (AC01), conta encerrada (AC04), devedor falecido (MD07)
Cancelamento quando o mesmo problema se repete	Sem mandato (MD01), devolução pedida pelo cliente (MD06), recusa do devedor (MS02), motivo não especificado

Se a subscrição tiver um mandato fixo definido (o seu campo mandateId), cancelá-la por estes motivos também revoga o mandato.

Uma ressalva: um artigo de ajuda mais antigo do Mollie indica outro limite para as subscrições SEPA (cancelamento após 2 falhas, não aplicável a fundos insuficientes). A documentação para programadores é a referência mais recente, mas teste o comportamento para os seus próprios métodos de pagamento em vez de assumir um número. Para fundos insuficientes (AM04), o centro de ajuda do Mollie sugere tentar de novo o débito direto ou contactar o cliente.

Duas consequências práticas:

• Precisa de saber quando o Mollie cancelou uma subscrição, porque a sua app tem de reagir. As subscrições canceladas não podem ser atualizadas pela API, por isso recuperar significa criar uma nova subscrição.
• As novas tentativas, por si só, não resolvem uma conta encerrada nem um mandato revogado. Esses clientes têm de voltar a pagar pelo checkout.

Webhooks que só trazem um ID

Os webhooks clássicos do Mollie são intencionalmente mínimos. Como explica a referência de webhooks, o Mollie chama o seu webhookUrl com um parâmetro POST id, o ID do objeto que mudou (para um pagamento, id=tr_...), e nada mais. O seu handler tem de obter o objeto na API e ler o seu estado atual.

O que construir à volta disto:

1. Obtenha sempre o objeto. Não deduza o que aconteceu pelo simples facto de ter chegado uma chamada. Leia o pagamento, verifique o estado e, nos pagamentos de subscrição, verifique o ID da subscrição e o estado da própria subscrição.
2. Devolva HTTP 200 depressa. O Mollie trata qualquer outra resposta, ou uma resposta mais lenta do que 15 segundos, como uma falha e volta a tentar com intervalos crescentes, até 10 tentativas ao longo de cerca de 26 horas. Não pode voltar a desencadear manualmente uma chamada de webhook a partir do Mollie.
3. Torne o processamento idempotente. O mesmo pagamento pode ser comunicado mais do que uma vez, e o estado que lê pode ter mudado desde que a chamada foi enviada.
4. Reconcilie de forma periódica. Como não pode reenviar chamadas, uma tarefa periódica que lista os pagamentos e as subscrições recentes apanha o que um endpoint em falha deixou escapar.

O Mollie oferece também next-gen webhooks, assinados com um cabeçalho X-Mollie-Signature calculado com o segredo do seu webhook. Se os usar, verifique a assinatura antes de agir. Em qualquer caso, trate a sua própria leitura na API como a fonte de verdade.

Chargebacks

Os clientes podem devolver pagamentos, e o Mollie expõe-nos através da Chargebacks API:

• GET /v2/chargebacks lista os chargebacks de todos os seus pagamentos, do mais recente para o mais antigo, com paginação.
• Os endpoints ao nível do pagamento listam ou obtêm os chargebacks de um pagamento.

No Débito Direto SEPA, um cliente pode devolver um pagamento no prazo de 8 semanas e, segundo o centro de ajuda do Mollie, o Mollie revoga o mandato após uma devolução. Qualquer cobrança seguinte precisa de um novo mandato, por isso um chargeback num pagamento recorrente é também um problema de método de pagamento, não apenas um montante perdido. Nas disputas de cartão, o artigo sobre chargebacks de cartão do Mollie explica que, consoante o caso, pode conseguir responder com documentação num número limitado de dias.

Quando chega um chargeback numa subscrição, decida de forma explícita: suspender o acesso, contactar o cliente ou terminar a subscrição. Não deixe que seja a próxima cobrança agendada a descobrir que o mandato desapareceu.

Pedir ao cliente que volte a pagar

Quando as novas tentativas se esgotaram, o mandato foi revogado ou a conta foi encerrada, recuperar significa trazer o cliente de volta ao checkout. O fluxo que segue o modelo documentado pelo Mollie:

1. Detete a falha no seu handler de webhook depois de obter o pagamento, e anote o motivo da falha a partir da referência status reasons, quando disponível.
2. Envie um email ao cliente no mesmo dia. Explique que o pagamento não passou, sem citar códigos bancários, e inclua um único link.
3. Aponte o link para um novo primeiro pagamento. Crie um pagamento para o mesmo cliente com sequenceType first pelo montante em dívida. Pagá-lo liquida o que é devido e cria um novo mandato num só passo. Os payment links do Mollie são outra forma de cobrar o montante, mas verifique se o método que usa cria um mandato para cobranças futuras.
4. Reinicie a subscrição no novo mandato quando o pagamento estiver pago. Se o Mollie já tiver cancelado a subscrição antiga, crie uma nova com uma data de início que corresponda ao período que o cliente acabou de pagar.
5. Envie lembretes se o link não for usado: passados alguns dias, depois um último aviso com a data em que o acesso termina.
6. Proponha outro método de pagamento no lembrete. Um cliente cuja conta bancária foi encerrada pode preferir um cartão, e o primeiro pagamento permite-lhe escolher.

Uma checklist

• O seu handler de webhook obtém cada objeto e devolve 200 depressa.
• Guarda o estado da subscrição e reage quando o Mollie a cancela.
• Os motivos definitivos (conta encerrada, IBAN inválido, mandato revogado) passam logo para um email “voltar a pagar”, sem esperar.
• Os fundos insuficientes têm tempo: as novas tentativas do próprio Mollie, mais um lembrete.
• Os chargebacks são verificados e marcam o mandato como inutilizável na sua app.
• Uma tarefa agendada reconcilia pagamentos e subscrições caso se tenham perdido chamadas de webhook.

Fazer isto com o NoChurn

O processamento de pagamentos, os mandatos, as novas tentativas do Mollie e os dados de cartão e bancários ficam todos no Mollie. O NoChurn liga-se à sua conta Mollie, importa clientes, mandatos e subscrições e, como os webhooks do Mollie só trazem um ID, volta a ler o pagamento antes de agir. Acrescenta emails de recuperação escritos por IA que revê antes do envio, com um link para voltar a pagar e configurar um novo método de pagamento. Os chargebacks aparecem em modo só de leitura na cronologia do cliente e contam para o score de churn de 0 a 100. O NoChurn acrescenta também fluxos de cancelamento com motivos, ofertas e um cancelamento num clique sempre visível, e emails de reconquista aos dias 30, 60 e 90 com base no motivo do cancelamento. Veja NoChurn + Mollie.