Como adicionar um fluxo de cancelamento às subscrições GoCardless

Um cliente de débito direto que quer sair tem duas saídas: a sua app ou o banco dele. Se a sua app dificultar, o banco está à distância de uma chamada, e um mandato cancelado ou um pedido de indemnização é um fim pior para os dois do que um cancelamento limpo. Um bom fluxo de cancelamento no GoCardless serve, portanto, em parte para manter clientes e em parte para garantir que os que saem o fazem através de si.

Este guia mostra o que a API Subscriptions do GoCardless lhe permite fazer quando um cliente quer cancelar e como construir por cima dela um fluxo de cancelamento curto. Baseia-se apenas na documentação do GoCardless: a referência da API de subscrições, a referência dos eventos de subscrição e o guia para developers Responding to mandate events (todos consultados em novembro de 2026). O site de documentação do GoCardless não estava acessível a partir do nosso ambiente de pesquisa, por isso verificámos o comportamento dos endpoints nas bibliotecas cliente oficiais da API do GoCardless, como a gocardless-pro-ruby, que são geradas a partir do mesmo esquema da API e têm as mesmas descrições.

O que o GoCardless lhe dá

Uma subscrição GoCardless cria pagamentos num mandato de acordo com o seu calendário. O seu status é um dos seguintes:

Estado	Significado
pending_customer_approval	À espera da aprovação do cliente
customer_approval_denied	O cliente não a aprovou
active	Vai continuar a criar pagamentos
paused	Não vai criar pagamentos
finished	Todos os pagamentos agendados foram criados
cancelled	Já não vai criar pagamentos

As quatro chamadas de que um fluxo de cancelamento precisa:

Cancelar

POST /subscriptions/:id/actions/cancel cancela imediatamente a subscrição; não são criados mais pagamentos ao abrigo dela. Falha com cancellation_failed se a subscrição já estiver cancelada ou terminada.

Um pagamento que já foi criado só pode ser cancelado enquanto o seu estado for pending_submission (POST /payments/:id/actions/cancel). Depois de submetido aos bancos, será cobrado ou falhará por si. Verifique os próximos pagamentos quando confirmar o cancelamento, para não prometer “nenhum outro pagamento” quando já há um a caminho.

Pausar e retomar

POST /subscriptions/:id/actions/pause impede a subscrição de criar pagamentos:

• Sem pause_cycles, fica em pausa até chamar o resume.
• Com pause_cycles, fica em pausa durante esse número de ciclos, e upcoming_payments continua a mostrar as datas de cobrança seguintes.
• Funciona para subscrições sem fim ou que cobram um número fixo (count) de pagamentos, não para as que têm uma end_date. Falha com subscription_cannot_be_paused quando não é possível pausar.

POST /subscriptions/:id/actions/resume retoma a criação de pagamentos. A data de cobrança do pagamento seguinte é a earliest_charge_date_after_resume da subscrição.

Isto faz da “pausa em vez de cancelamento” uma oferta nativa no GoCardless, o que não acontece em todas as plataformas de pagamento.

Atualizar

PUT /subscriptions/:id altera campos como o montante. O GoCardless documenta limites que importam para as ofertas de desconto:

• Falha com number_of_subscription_amendments_exceeded se o montante já tiver sido alterado 10 vezes.
• Falha com mandate_payments_require_approval se o montante mudar e o mandato exigir aprovação.
• Falha com subscription_not_active se a subscrição já não estiver ativa.

Um desconto temporário custa, portanto, duas alterações (para baixo e depois de volta para cima). Faça as contas.

Deixe o mandato em paz

Cancelar uma subscrição não cancela o mandato. O guia para developers do GoCardless diz para cancelar um mandato apenas se o cliente o tiver pedido explicitamente. Mantê-lo significa que um cliente que regressa pode recomeçar sem configurar um novo débito direto. Se o cliente lhe pedir para cancelar o próprio débito direto, faça-o e diga-o na confirmação.

Desenhar o fluxo

1. Perguntar porquê

Uma pergunta, uma lista curta, um toque:

• Demasiado caro
• Não o uso o suficiente
• Só precisava durante algum tempo
• Falta-me alguma coisa
• Vou mudar para outro fornecedor
• Outro

Guarde o motivo com o cliente. Também o pode pôr nos metadata da subscrição antes de cancelar, para que fique com o registo do GoCardless.

2. Uma oferta que corresponda ao motivo

Motivo	Oferta	No GoCardless
Só precisava durante algum tempo	Pausa de 1 a 3 ciclos	pause com pause_cycles
Demasiado caro	Um preço mais baixo durante alguns meses	update do montante, agendar a atualização de volta (2 alterações)
Não o uso o suficiente	Um plano mais barato	update do montante, ou cancelar e criar uma nova subscrição no mesmo mandato
Falta-me alguma coisa, vou mudar	Nenhum desconto; pedir detalhes	Nada a alterar

Indique o efeito exato antes de o cliente aceitar: para uma pausa, a data da próxima cobrança; para um desconto, o montante reduzido, quantos pagamentos abrange e o montante depois.

3. Cancelar, sempre visível

O botão de cancelar pertence a todos os passos, não só depois da oferta. Um cliente que recusa a oferta está a um clique da confirmação, que diz:

• que a subscrição está cancelada;
• se algum pagamento já submetido ainda vai ser cobrado, e a sua data;
• até quando mantém o acesso;
• se o mandato de débito direto se mantém (e como o cancelar também, se quiser).

Este último ponto importa no débito direto. Um cliente que vê um mandato ainda listado no seu banco pode cancelá-lo lá “por precaução”. Está no seu direito, e é melhor que saiba que não é necessário.

Ligar tudo

1. Carregue a subscrição e os próximos pagamentos quando o fluxo abre.
2. Use uma chave de idempotência nas chamadas pause, resume e cancel (as bibliotecas cliente oficiais do GoCardless tratam os conflitos de idempotência nestas ações) e desative os botões depois do primeiro clique.
3. Escute os eventos de subscrição (veja a referência dos eventos para a lista completa de ações) para que a sua app se mantenha sincronizada quando as alterações vêm do dashboard ou do próprio GoCardless, por exemplo quando um mandato é cancelado e as suas subscrições com ele.
4. Agende os acompanhamentos de que as suas ofertas precisam: a atualização de volta ao preço completo, o fim de uma pausa sem prazo, um lembrete antes de uma subscrição em pausa recomeçar.
5. Registe cada passo: motivo, oferta mostrada, resposta, hora do cancelamento. Se mais tarde chegar um pedido de indemnização, este registo ajuda a perceber o que correu mal.

Medir o que importa

• Ofertas aceites, por motivo.
• Subscrições em pausa que são retomadas e continuam a pagar três meses depois.
• Cancelamentos através do seu fluxo comparados com mandatos cancelados no banco. Se muitos clientes saem através do banco, a opção de cancelar é demasiado difícil de encontrar.

Fazer isto com o NoChurn

O GoCardless mantém a subscrição, o mandato e a cobrança. O NoChurn acrescenta o fluxo de cancelamento: motivos, uma oferta que corresponde a cada motivo e um cancelamento num clique sempre visível, alojado pelo NoChurn ou integrado na sua própria interface com a API headless. No GoCardless, um cancelamento termina a subscrição GoCardless e o mandato fica como o cliente escolher. Os motivos de cancelamento acionam emails de reconquista aos dias 30, 60 e 90 e alimentam a pontuação de churn. Veja NoChurn + GoCardless.