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

A faturação recorrente do Braintree tem uma única operação de cancelamento, e é definitiva: uma subscrição cancelada não pode ser editada nem reativada. Não há página de cancelamento integrada, nem inquérito de motivos, nem oferta de retenção. Se quiser que os clientes vejam uma alternativa antes de saírem, e guardar um registo de porque saíram, cria esse fluxo na sua app e chama o Braintree no fim.

Este guia cobre as operações do Braintree de que um fluxo de cancelamento depende, os limites que o condicionam e um desenho passo a passo. Baseia-se na documentação do próprio Braintree: Subscription: Cancel, Subscription: Update, Manage subscriptions, Plans, Statuses, Subscription webhooks e o guia de subscrições (todos consultados em novembro de 2026).

Como funciona o cancelamento no Braintree

O Subscription: Cancel passa uma subscrição para Canceled, que a referência de estados do Braintree descreve como não havendo mais faturação. A referência é explícita: depois de cancelada, uma subscrição não pode ser editada nem reativada; um cliente que regressa precisa de uma nova subscrição.

Três consequências para o seu fluxo:

• Cancelar é o último passo, nunca o primeiro. Apresente todas as ofertas antes da chamada.
• Não existe uma flag “cancelar no fim do período” na operação de cancelamento. Se cancelar a meio do ciclo, a faturação para, e aquilo a que o cliente continua a ter acesso é uma decisão sua, na sua app.
• Guarde a data de cancelamento por si. O Braintree nota que a data de cancelamento não está incluída nos resultados de pesquisa de subscrições e sugere capturá-la a partir do webhook subscription_canceled.

Terminar no fim do período pago

Muitos negócios querem que o cliente mantenha o acesso até ao fim do que pagou, sem mais cobranças. Duas abordagens encaixam no modelo do Braintree:

1. Cancelar já e manter o acesso na sua app até ao fim do período de faturação atual, usando a data de fim de período que guardou para a subscrição.
2. Limitar o número de ciclos de faturação. O Subscription: Update permite definir o número de ciclos de faturação, que tem de ser maior ou igual ao ciclo de faturação atual, e desativa o “never expires”. Quando uma subscrição atinge o número de ciclos definido, o Braintree marca-a como Expired. Isto deixa a subscrição terminar naturalmente depois do ciclo atual, e um cliente que mude de ideias antes disso pode ser reposto voltando a definir que nunca expira.

A segunda abordagem mantém a subscrição editável até terminar, o que facilita o “anular”. Teste-a em sandbox com as definições dos seus planos antes de contar com ela.

O que pode oferecer em alternativa

A operação de atualização do Braintree dá-lhe as alavancas para as ofertas de retenção.

Descontos

Pode adicionar, atualizar ou remover descontos (e add-ons) numa subscrição existente. Regras principais da documentação:

• Os detalhes do desconto (nome, valor, duração) são geridos no Control Panel, não pela API. Crie primeiro lá os seus descontos de retenção e depois aplique-os pelo ID.
• Um dado desconto só pode ser aplicado uma vez a uma subscrição; para o aplicar mais do que uma vez, use a sua quantidade.

Crie um desconto de retenção dedicado, por exemplo “Retention 30% x3”, para que as ofertas aceites sejam fáceis de encontrar nos relatórios e nunca se confundam com descontos comerciais.

Mudanças de preço e de plano

Pode mudar o preço da subscrição, com uma flag que controla se a alteração é proporcional, ou passá-la para outro plano. O Braintree nota que mudar para um plano com uma frequência de faturação diferente só está disponível para comerciantes selecionados que o peçam, e reinicia o ciclo de faturação atual. Para a maioria dos fluxos de cancelamento, um downgrade para um plano mais barato com a mesma frequência é a oferta mais simples.

Uma pausa

A documentação do Braintree que analisámos não descreve uma operação de pausa ou de “saltar um ciclo” para subscrições. O webhook subscription_billing_skipped existe, mas é disparado quando um ciclo é saltado porque um saldo nulo ou negativo já o cobre, não a pedido. Se quiser oferecer uma pausa, teria de a construir por cima do Braintree (por exemplo com um desconto total temporário durante um número definido de ciclos), e testar primeiro com cuidado o comportamento da faturação.

Webhooks que o seu fluxo deve ouvir

Dos webhooks de subscrição do Braintree:

Tipo	Utilização num fluxo de cancelamento
subscription_canceled	Registar a data de cancelamento, revogar o acesso quando devido, iniciar a reconquista
subscription_expired	A subscrição chegou ao último ciclo (na abordagem dos “ciclos limitados”)
subscription_charged_successfully	Confirma que o preço de uma oferta foi cobrado

Ouça-os mesmo para cancelamentos que o próprio sistema desencadeia. Os agentes de suporte podem cancelar a partir do Control Panel, e esses cancelamentos devem ir parar aos mesmos registos.

Construir o fluxo

1. Encaminhe o botão de cancelar para a sua própria página, nunca diretamente para a API.

2. Pergunte porquê. Cinco a sete motivos mais “Outro”. Guarde a resposta com o ID da subscrição do Braintree. Ideias em inquéritos sobre motivos de cancelamento.

3. Mostre uma oferta que corresponda ao motivo:

   Motivo	Oferta	Operação no Braintree
   Demasiado caro	Desconto por tempo limitado	Update: adicionar um desconto de retenção
   Preciso de menos	Plano mais barato	Update: mudar o plano ou o preço
   Não estou a usar agora	Uma pausa, se a tiver construído	A sua própria lógica (ver acima)
   Problema técnico	Ajuda do suporte	Nenhuma até estar resolvido
   Vou mudar ou fechar	Sem oferta	Cancel

4. Mantenha “Cancelar subscrição” visível em todas as etapas, tão fácil de clicar como a oferta. Regras e boas práticas em regras de click to cancel e boas práticas de fluxos de cancelamento.

5. Se aceitar, chame o Subscription: Update e confirme por email com o novo preço e a sua duração.

6. Se cancelar, chame o Subscription: Cancel (ou limite os ciclos de faturação), mostre a data em que o acesso termina e envie uma confirmação.

7. Trate as subscrições em atraso. Um cliente que cancela com pagamentos em atraso pode dever um saldo; decida a sua política e mostre-a.

8. Reveja todos os meses que motivos surgem mais e que ofertas ainda estão a pagar ao fim de três meses.

Erros comuns

• Cancelar e depois tentar aplicar uma oferta. As subscrições canceladas não podem ser editadas.
• Criar descontos no código. Os detalhes dos descontos vivem no Control Panel; planeie-os com antecedência.
• Perder a data de cancelamento. Sem o webhook guardado, não consegue calendarizar os emails de reconquista nem medir o churn por mês.
• Esconder a opção de cancelar atrás da oferta. Custa confiança e, em muitos sítios, viola as regras.

Fazer isto com o NoChurn

O Braintree fica com a subscrição, os pagamentos e o próprio cancelamento. O fluxo de cancelamento do NoChurn pergunta o motivo, mostra uma oferta (um desconto, uma mudança de plano ou um cancelamento na subscrição do Braintree) e mantém um cancelamento com um clique visível em todas as etapas, alojado ou headless através da API. As respostas alimentam os emails de reconquista aos 30, 60 e 90 dias e um score de churn de 0 a 100, e tornam-se provas se o cliente vier a contestar uma cobrança. Veja NoChurn + Braintree.