Como recuperar pagamentos falhados no Zuora

O Zuora dá-lhe muito controlo sobre a cobrança dos pagamentos, o que também significa muitas definições a acertar. Os pagamentos falhados no Zuora tocam pelo menos quatro áreas: os payment runs, as regras de novas tentativas, as notificações e a forma como os clientes atualizam o seu meio de pagamento. Este guia percorre cada uma e termina com um plano de configuração prático.

Baseia-se apenas na documentação do próprio Zuora: Payment runs, Configure payment retry rules, Payment Retry, Configurable Payment Retry, Payment attempts and retry rules, Standard events for Zuora Payments e How do I allow customers to modify their stored payment methods? (todos consultados em novembro de 2026). Os nomes dos campos podem variar com a versão do seu tenant, por isso verifique-os nas suas próprias definições.

Passo 1: perceber os payment runs

No Zuora, a cobrança automática faz-se através dos payment runs. Um payment run cobra as faturas em aberto com meios de pagamento eletrónicos como cartões ou ACH. Segundo a documentação dos payment runs:

• Um run pode processar até 200.000 faturas.
• Há runs ad hoc, que inicia à mão, e runs recorrentes, que correm segundo um calendário diário, semanal ou mensal.
• Os runs só cobram as contas com auto-pay ativo. O auto-pay é definido em cada conta de cliente, por isso uma conta sem ele nunca será cobrada por um run, e as suas faturas ficam simplesmente em aberto.
• Quando uma fatura está a ser processada por um pagamento, fica bloqueada, e qualquer outro pagamento sobre ela falha. O Zuora recomenda decidir que faturas são cobradas por que método (payment run, payment page, API) para que não colidam.

A primeira coisa a verificar quando “o Zuora não está a tentar de novo” muitas vezes nem tem a ver com as novas tentativas: é saber se a conta tem o auto-pay ativo e um meio de pagamento eletrónico por defeito.

Passo 2: escolher o mecanismo de novas tentativas

O Zuora tem duas formas de voltar a tentar um pagamento eletrónico falhado. O Zuora desaconselha usar as duas ao mesmo tempo.

Regras de novas tentativas ao nível do tenant

As regras incluídas, descritas em Configure payment retry rules, aplicam-se por defeito ao processamento de pagamentos falhados quando as novas tentativas de pagamento estão ativas no seu tenant. Define:

• o número máximo de vezes consecutivas que um meio de pagamento falhado é tentado de novo;
• um intervalo mínimo desde a última tentativa falhada (por exemplo, com 8 horas, não há nova tentativa automática se a última falha tiver sido há menos de 8 horas);
• um período durante o qual os pagamentos não são tentados de novo.

Pode substituir estas regras por meio de pagamento. São simples e previsíveis, mas as mesmas regras aplicam-se a todas as recusas, seja qual for o motivo.

Configurable Payment Retry (CPR)

O Configurable Payment Retry é a opção mais flexível do Zuora. Permite definir a lógica de novas tentativas por grupo de clientes e por código de resposta do gateway, associando os códigos a categorias como hard, medium e soft declines. Pontos-chave da documentação:

Definição ou comportamento	O que o Zuora documenta
Janela de novas tentativas	Dias desde a entrada em novas tentativas até à última tentativa, máximo 90 dias
Número de tentativas	Máximo 20; o payment run faz a primeira tentativa, o CPR faz as restantes
Smart Retry	Um modelo de machine learning opcional que escolhe os momentos das novas tentativas a partir das características do subscritor e da transação
Hard declines	Uma opção Stop Retry On Hard Declines termina o ciclo perante uma hard decline
Momento	As tentativas correm em lotes à hora certa, por isso as novas tentativas não podem ser mais frequentes do que de hora a hora
Meios de pagamento	Apenas pagamentos com cartão, não débitos diretos como ACH ou SEPA
Alterações de regras	Aplicam-se apenas às tentativas futuras; os ciclos concluídos não são recomeçados

Dois comportamentos das boas práticas do CPR são fáceis de ignorar:

• O CPR desativa o auto-pay enquanto corre um ciclo de novas tentativas, para que o payment run normal não cobre a fatura de novo. Segundo a página das definições de auto-pay, o que muda depende do nível das novas tentativas: ao nível da fatura, só a marca de auto-pay da fatura é desativada; ao nível da conta, o auto-pay da conta é desativado e só volta a ser ativado quando o pagamento é cobrado. O Zuora recomenda as novas tentativas ao nível da fatura, que mantêm a conta elegível para os payment runs futuros. Uma página de boas práticas mais antiga descreve as duas marcas a passar para false, por isso verifique que nível o seu tenant usa.
• Para parar as novas tentativas de imediato (por exemplo, o cliente pagou por transferência bancária), termina manualmente o ciclo de novas tentativas, o que pode fazer através das APIs do CPR.

Se não souber como classificar um código de resposta, o Zuora sugere associá-lo a uma soft decline e acompanhar os resultados. O Zuora documenta também uma forma de testar o Smart Retry face à sua lógica existente antes de mudar tudo.

Passo 3: avisar o cliente, com notificações e callouts

As novas tentativas recuperam as recusas temporárias. Os cartões expirados, substituídos ou bloqueados precisam do cliente. Os standard events para pagamentos do Zuora dão-lhe os pontos de ligação:

• Payment Declined: dispara quando o gateway recusa um pagamento eletrónico. Uma definição “Sequence of failed attempt” controla em que falha consecutiva a notificação dispara; é comparada com o NumConsecutiveFailures do meio de pagamento e por defeito é 1. Os pagamentos externos não desencadeiam estas notificações.
• Avisos de expiração do cartão: eventos 15 e 30 dias antes de o cartão por defeito expirar (a data de expiração é o último dia do mês de expiração). Permitem pedir um cartão novo antes de alguma coisa falhar.
• Payment Method Updated: dispara quando o meio de pagamento por defeito muda, o que é o seu sinal para parar os lembretes.

Cada notificação pode ser entregue como email ou como callout, um pedido HTTP para o seu endpoint, configurado na definição da notificação. Use os callouts para atualizar a sua própria app (banner, acesso) e para desencadear as mensagens que envia fora do Zuora. O Zuora Workflow pode também reagir a estes eventos e enviar emails a partir de modelos ou chamar APIs externas, se preferir manter a lógica dentro do Zuora.

Um plano de notificações simples:

Gatilho	Mensagem	Canal
O cartão expira em 30 dias	“O seu cartão expira em breve, atualize-o aqui”	Email
Primeiro pagamento recusado	“O seu pagamento não foi concluído”, com o link de atualização	Email e na app
Terceira falha consecutiva	Lembrete com a data em que o acesso é afetado	Email
Meio de pagamento atualizado	Confirmação, sem mais lembretes	Email

Passo 4: deixar o cliente atualizar o meio de pagamento

O link de atualização nesses emails precisa de um destino. O Zuora documenta três formas de alterar um meio de pagamento guardado no seu guia sobre a alteração dos meios de pagamento guardados:

1. A hosted payment method page para cartões de crédito, passando o ID do meio de pagamento existente (pmId) para que o cliente possa atualizar os dados do cartão. É o caminho que mantém os dados do cartão fora dos seus servidores; o Zuora recomenda as Payment Pages 2.0 em vez de tratar os dados do cartão através da API.
2. A operação REST Update a payment method. A referência da API do Zuora recomenda vivamente as Payment Pages 2.0 em vez de a chamar diretamente, e enviar um número de cartão por ela coloca os seus próprios sistemas no âmbito do PCI.
3. A interface do Zuora, na secção Electronic Payment Methods da conta do cliente, para os agentes de suporte.

Depois de guardado um novo meio de pagamento por defeito, garanta que a fatura em aberto é efetivamente cobrada, seja pelo próximo payment run (verifique o auto-pay, que o CPR pode ter desativado) seja por um pagamento imediato. Lembre-se do bloqueio das faturas: não deixe uma payment page e um payment run cobrarem a mesma fatura ao mesmo tempo.

Uma checklist de recuperação para o Zuora

1. Audite o auto-pay em todas as contas com subscrições ativas e confirme que existe um meio de pagamento eletrónico por defeito.
2. Escolha um único mecanismo de novas tentativas: as regras do tenant pela simplicidade, o CPR pela lógica sensível às recusas e pelos grupos de clientes. Não os dois.
3. Associe os códigos de resposta no CPR e ative o Stop Retry On Hard Declines, para que um cartão roubado não seja tentado de novo durante semanas.
4. Mantenha a janela de novas tentativas mais curta do que o período de faturação nos planos mensais.
5. Ative os avisos de expiração do cartão a 30 e 15 dias, e veja o Payment Method Updater, que pede aos serviços de updater da Visa, Mastercard e American Express os novos dados do cartão antes do bill cycle day nos gateways suportados.
6. Configure a notificação Payment Declined com um link para uma hosted payment page, mais um callout para a sua app.
7. Cobre depois de uma atualização: confirme que a fatura é cobrada assim que um cartão novo é guardado.
8. Reveja as recusas mensalmente por código de resposta e grupo de clientes.

Fazer isto com o NoChurn

O Zuora continua responsável pela faturação, pelos payment runs, pelas novas tentativas e pelo seu gateway. O NoChurn conecta-se através de um cliente OAuth do Zuora, importa as contas e as subscrições, recebe as notificações do Zuora e acrescenta emails de recuperação escritos pela IA que revê antes de saírem, com um link para atualizar o meio de pagamento. Acrescenta também fluxos de cancelamento com motivos, ofertas (um desconto ou uma mudança de plano na subscrição do Zuora) e um cancelamento num clique sempre visível, emails de reconquista aos 30, 60 e 90 dias consoante o motivo do cancelamento, e um score de churn de 0 a 100. As disputas vêm do gateway por trás do Zuora; com o Stripe ou o Braintree, o NoChurn reúne as provas e redige uma resposta para rever. Veja NoChurn + Zuora.