Os decline codes do Stripe explicados: o que fazer em cada um

Quando uma renovação falha no Stripe, a cobrança volta com uma pequena cadeia de texto como insufficient_funds ou do_not_honor. Essa cadeia é a informação mais útil que recebe sobre a falha. Diz-lhe se uma nova tentativa pode resultar, se o cliente tem de fazer alguma coisa e o que lhe pode dizer.

Este guia percorre os decline codes mais importantes para as subscrições, agrupados pelo que deve fazer em cada caso. Baseia-se no que o Stripe documenta na sua referência de decline codes e no seu guia de recusas de cartão (ambos consultados em novembro de 2026), e di-lo quando as próprias páginas do Stripe deixam margem para interpretação.

Onde estão os códigos

Um pagamento com cartão falhado no Stripe pode trazer vários campos. Respondem a perguntas diferentes:

Campo	O que lhe diz	Onde o encontrar
decline_code	O motivo normalizado do Stripe para a recusa do emissor, se o emissor deu um	No erro, e em last_payment_error do PaymentIntent
advice_code	O que fazer a seguir: tentar de novo, não tentar de novo, ou verificar os dados do cartão	No erro, ao lado do decline code
network_decline_code	O código em bruto da rede de cartões	No resultado da cobrança
network_advice_code	O conselho da própria rede (na Mastercard, os seus Merchant Advice Codes)	No resultado da cobrança

O Stripe acrescentou os campos network advice e decline code à API em dezembro de 2024. A documentação do Stripe avisa que o significado de um network_decline_code difere entre redes de cartões, por isso leia-o sempre junto com a marca do cartão.

Nas subscrições, normalmente lê-os a partir do webhook invoice.payment_failed: vá buscar o PaymentIntent da fatura e olhe para last_payment_error.

Os advice codes primeiro

O advice_code é o sinal mais simples, e o guia de recusas de cartão do Stripe documenta três valores:

• try_again_later: o emissor recusou, mas pode tentar de novo. Se as novas tentativas repetidas falharem, o cliente tem de contactar o seu emissor.
• do_not_try_again: não use este cartão de novo para esta transação. Veja o decline code para saber o motivo.
• confirm_card_data: o emissor recusou porque alguma informação do cartão estava errada. O cliente tem de verificar os seus dados.

Se houver um advice code, deixe-o prevalecer sobre qualquer regra geral. Um do_not_try_again naquilo que parece uma soft decline significa parar.

Soft vs hard declines

O Stripe não classifica todos os códigos como soft ou hard, mas a distinção é útil e o Stripe usa-a na sua documentação sobre novas tentativas:

• As soft declines são temporárias. O cartão é válido; o emissor disse não desta vez. Tentar de novo mais tarde pode resultar.
• As hard declines significam que o cartão não pode ser cobrado tal como está. A página de Smart Retries do Stripe enumera os códigos que não volta a tentar sem um novo meio de pagamento: incorrect_number, lost_card, pickup_card, stolen_card, revocation_of_authorization, revocation_of_all_authorizations, authentication_required, highest_risk_level e transaction_not_allowed.

Para esses hard decline codes, o Stripe continua a agendar novas tentativas na fatura, mas uma cobrança só é feita quando for associado um novo meio de pagamento. Se ninguém pedir ao cliente, nada acontece. Explicamos o lado das novas tentativas em detalhe em como funcionam as Smart Retries do Stripe.

Os códigos comuns, e o que fazer

A tabela abaixo cobre os códigos que verá mais nas renovações de subscrições. “Próximo passo segundo o Stripe” parafraseia a referência de decline codes; “Numa subscrição” é a nossa leitura prática.

Código	Descrição e próximo passo segundo o Stripe	Nova tentativa?	Numa subscrição
insufficient_funds	Saldo insuficiente; o cliente deve usar outro meio de pagamento	Sim, mais tarde	Tentar de novo num momento melhor (depois de um provável dia de salário); enviar email ao cliente com um link de atualização
generic_decline	Recusado por um motivo desconhecido, ou bloqueado pelo Radar; o cliente contacta o emissor	Algumas vezes	Tentar de novo; enviar email; sugerir que o cliente ligue ao banco ou tente outro cartão
do_not_honor	Recusa genérica do emissor sem motivo específico	Algumas vezes	Igual a generic_decline
processing_error	Erro ao processar o cartão; tentar de novo e depois contactar o emissor	Sim	Tentar de novo em breve; enviar email só se continuar a falhar
card_velocity_exceeded	O cliente ultrapassou o saldo, o limite de crédito ou o limite de transações; contactar o emissor	Sim, mais tarde	Tentar de novo mais tarde; mencionar um limite de gastos no email
expired_card	O cartão expirou; usar outro cartão	Não	Verificar primeiro se houve atualização automática do cartão; caso contrário pedir um cartão novo
incorrect_cvc	O CVC está incorreto; tentar de novo com o CVC correto	Não	Pedir ao cliente que volte a introduzir o cartão na página de atualização
incorrect_number	O número do cartão está incorreto	Não	Pedir um cartão novo
lost_card, stolen_card	Reportado como perdido ou roubado; apresentar como recusa genérica	Não	Pedir um cartão novo, sem mencionar o motivo
pickup_card	O cartão não pode ser usado para este pagamento (possivelmente reportado como perdido ou roubado); contactar o emissor	Não	Pedir um cartão novo
fraudulent	O Stripe suspeita de fraude; mostrar a mesma mensagem que numa recusa genérica	Não	Tratar com cuidado; não revelar o motivo
authentication_required	O banco exige que o cliente se autentique	Não sem o cliente	Enviar um link para confirmar o pagamento; veja SCA nas renovações
revocation_of_authorization, stop_payment_order	O Stripe enumera-os com motivo desconhecido; o cliente contacta o emissor	Não	Pedir um novo meio de pagamento; verificar se o cliente queria deixar de pagar
transaction_not_allowed	Não permitido neste cartão	Não	Pedir outro cartão ou meio de pagamento

Há dois pontos fáceis de ignorar:

1. Alguns motivos não podem ser mostrados ao cliente. Para lost_card, stolen_card e fraudulent, a referência do Stripe diz para apresentar a recusa como uma recusa genérica. O seu email de recuperação deve dizer “o seu pagamento foi recusado”, nunca “o seu cartão foi reportado como roubado”.
2. “Contacte o seu emissor” é uma instrução real. Nas recusas genéricas, uma chamada ao banco resolve muitas vezes o bloqueio. Pode dizê-lo no email, de forma breve.

Os limites de novas tentativas são reais

Tentar de novo não é gratuito, mesmo nas soft declines. As redes de cartões limitam a frequência com que um comerciante pode tentar de novo um cartão recusado, e os emissores podem tratar novas tentativas excessivas como um sinal de fraude.

Segundo o artigo de suporte do Stripe sobre pagamentos bloqueados por novas tentativas excessivas (consultado em novembro de 2026), as regras da Visa proíbem de forma geral mais de 15 novas tentativas de um mesmo pagamento em 30 dias. Para transações Visa com preço integrado, o Stripe bloqueia as novas tentativas depois da 15.ª quando considera baixa a probabilidade de sucesso. Os valores por defeito do próprio Stripe (8 tentativas nas Smart Retries) ficam bem abaixo disso, mas uma lógica de novas tentativas própria fora do Stripe pode ultrapassá-lo se não tiver cuidado.

O sinal equivalente da Mastercard é o Merchant Advice Code, que o Stripe expõe como network_advice_code. A documentação dos processadores, como a referência de merchant advice codes do Braintree, descreve códigos que significam “não tentar de novo” e um que significa que o titular do cartão cancelou o pagamento recorrente. Quando os vir, deixe de tentar esse cartão.

Regras práticas:

• Conte todas as tentativas por fatura, incluindo as que o seu próprio código desencadeia.
• Pare de imediato perante uma hard decline ou um conselho do_not_try_again.
• Não tente o mesmo cartão várias vezes no mesmo dia “por via das dúvidas”.
• Espace as novas tentativas das soft declines e alinhe-as com os momentos em que o dinheiro deverá estar disponível.

O que dizer ao cliente, por grupo

A maioria das equipas envia o mesmo email para todas as falhas. Algumas variações por grupo de recusa funcionam melhor e não dão muito mais trabalho.

Grupo	Códigos	Mensagem do email
Saldo ou limites	insufficient_funds, card_velocity_exceeded	“Vamos tentar de novo a [data]. Se preferir usar outro cartão, atualize-o aqui.”
Pouco claro	generic_decline, do_not_honor, processing_error	“O seu banco recusou o pagamento. Muitas vezes é um bloqueio temporário; uma chamada rápida ao banco, ou outro cartão, costuma resolver.”
Cartão inutilizável	expired_card, lost_card, stolen_card, pickup_card, incorrect_number	“Precisamos de um cartão novo para manter a sua subscrição ativa.” Sem indicar o motivo.
Autenticação	authentication_required	“O seu banco pede-lhe que confirme este pagamento. Demora um minuto.”
Dados do cartão	incorrect_cvc, conselho confirm_card_data	“Alguns dados do cartão não coincidiam. Volte a introduzir o seu cartão.”

Tem emails prontos a usar para cada passo nos nossos modelos de emails de recuperação.

Registar bem os decline codes

Não pode melhorar o que não mede. Para cada renovação falhada, guarde:

• ID da fatura, ID do cliente, montante e moeda.
• Número e data da tentativa.
• decline_code, advice_code, network_decline_code, network_advice_code.
• Marca do cartão, tipo de financiamento (crédito, débito, pré-pago) e país.
• Resultado: recuperado (e como: nova tentativa, cartão novo, autenticação) ou perdido.

Com alguns meses de dados, consegue responder às perguntas que importam: que códigos se recuperam com uma nova tentativa e quais só se recuperam quando o cliente age, se os cartões pré-pagos falham mais vezes (veja cartões pré-pagos e virtuais), e se são os seus emails ou as suas novas tentativas que fazem a maior parte do trabalho.

Agrupar para os relatórios

Os códigos em bruto são demasiado detalhados para um relatório mensal. Agrupe-os:

Grupo do relatório	Códigos
Soft: saldo	insufficient_funds, card_velocity_exceeded
Soft: pouco claro	generic_decline, do_not_honor, processing_error, try_again_later
Hard: cartão	expired_card, lost_card, stolen_card, pickup_card, incorrect_number, incorrect_cvc
Hard: autorização	revocation_of_authorization, revocation_of_all_authorizations, stop_payment_order, transaction_not_allowed
Autenticação	authentication_required
Risco	fraudulent, highest_risk_level

Mantenha o código em bruto nos seus dados para poder reagrupar mais tarde. O Stripe acrescenta e descontinua códigos ao longo do tempo; a referência do Stripe marca agora alguns códigos mais antigos como obsoletos em favor dos advice codes.

Testar o tratamento das recusas

O Stripe disponibiliza números de cartão de teste que desencadeiam decline codes específicos. Antes de pôr em produção qualquer lógica de recuperação, passe cada grupo pelo modo de teste:

• Uma soft decline agenda uma nova tentativa e envia o primeiro email.
• Uma hard decline envia um email “é preciso um cartão novo” e não tenta de novo o mesmo cartão.
• authentication_required envia um link de confirmação.
• lost_card e stolen_card produzem uma mensagem genérica.
• Um pagamento bem-sucedido (invoice.paid) para todos os emails e novas tentativas.
• Cada tentativa é registada com os seus códigos.

Erros comuns

• Tratar todas as recusas da mesma forma. Tentar oito vezes um cartão roubado não recupera nada e pode contar contra si junto da rede.
• Dizer ao cliente o motivo em bruto. “Do not honor” não significa nada para os clientes, e alguns motivos não podem de todo ser revelados.
• Ignorar os advice codes. Existem precisamente para lhe dizer se deve tentar de novo.
• Ler apenas a primeira falha. O código pode mudar entre tentativas; um cartão pode passar de insufficient_funds a expired_card ao longo de uma janela de novas tentativas longa.
• Nenhuma saída para as hard declines. Se o único caminho para a recuperação for uma nova tentativa, as hard declines estão perdidas à partida.

Para o panorama completo da recuperação de pagamentos falhados, das novas tentativas aos emails e à medição, veja como recuperar pagamentos falhados no Stripe.

Como o NoChurn ajuda

O NoChurn lê o decline code de cada renovação falhada e trata cada grupo de forma diferente. As soft declines são tentadas de novo em momentos baseados nos prováveis dias de salário e na hora local do cliente (ou mantém as Smart Retries do Stripe). As hard declines e os pedidos de autenticação evitam novas tentativas inúteis e passam diretamente para um email de recuperação escrito pela IA, revisto antes do envio, com um link para uma página alojada de atualização do cartão. Os motivos sensíveis nunca são mostrados ao cliente, e cada decisão é registada com o seu código.

Conecta-se ao Stripe com um clique, e o preço depende apenas do MRR, sem nenhuma parte da receita recuperada. Veja pagamentos falhados e preços.