Falhas de Transação

Visão Geral

Quando uma tentativa de pagamento falha, Dodo Payments retorna um código de falha padronizado que informa o motivo. Os códigos são os mesmos em todos os métodos de pagamento e processadores de pagamento, portanto, um único conjunto de regras de tratamento abrange todos os pagamentos com falha. O webhook payment.failed e o objeto de pagamento expõem estes campos para um pagamento com falha:

error_code: um código de falha padronizado da tabela abaixo.
error_message: uma explicação escrita para você, o merchant. Quando error_code é um dos códigos padronizados abaixo, este campo contém um título e a ação recomendada, não o texto bruto do processador de pagamento.
retry_attempt: 0 para a cobrança original e 1 ou superior para cada nova tentativa agendada de renovação de assinatura. Pagamentos que não são renovações de assinatura mantêm o valor 0.

Use estes códigos para fornecer feedback claro aos clientes, decidir se uma nova tentativa pode ser bem-sucedida e recuperar mais receita.

Texto para o Merchant vs. Texto para o Customer

Cada código de falha padronizado corresponde a duas mensagens, uma para você e outra para seu cliente:

Público	Onde aparece	O que informa
Você	`error_message` no pagamento, na página de detalhes do pagamento no dashboard e no e-mail de falha de pagamento recebido pelos merchants	O motivo real e uma ação recomendada, por exemplo: “O cartão ainda não foi ativado pelo titular. Peça ao cliente para ativá-lo com o banco e tente novamente.”
Seu cliente	Na tela de falha do checkout, no Customer Portal e nos e-mails de dunning	Uma explicação curta e em linguagem simples que o cliente pode resolver, por exemplo: “Seu cartão ainda não foi ativado. Ative-o com seu banco e tente novamente.”

O Customer Portal retorna o texto destinado ao cliente em error_message, enquanto a API do merchant retorna o texto destinado ao merchant para o mesmo pagamento. O error_code é o mesmo em ambos.

Handle Payment Failures

Um guia de desenvolvimento passo a passo para ler esses códigos em webhooks e na API, exibi-los aos clientes e decidir quando tentar novamente.

Recusas temporárias e permanentes

Cada código de falha é uma recusa temporária ou definitiva. O tipo informa se uma tentativa posterior com os mesmos dados de pagamento pode ser bem-sucedida ou se o cliente precisa agir primeiro.

Tipo de recusa	O que significa	O que fazer	Exemplos
Recusa temporária	Temporária. Os mesmos dados de pagamento podem funcionar em uma tentativa posterior.	Tente novamente após um intervalo.	`INSUFFICIENT_FUNDS`, `GENERIC_DECLINE`, `CARD_VELOCITY_EXCEEDED`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `TRY_AGAIN_LATER`
Recusa definitiva	Uma nova tentativa com os mesmos dados de pagamento e sem nenhuma ação do cliente não altera o resultado.	Não tente novamente com os mesmos dados. Peça ao cliente para corrigir os dados, concluir a autenticação, entrar em contato com o banco ou usar outro método de pagamento.	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`, `INCORRECT_CVC`

Para renovações de assinatura, Dodo Payments aplica essa classificação automaticamente. Subscription Payment Retries tenta novamente pagamentos recusados temporariamente. Uma recusa definitiva encerra imediatamente a cadeia de novas tentativas; recupere-a com Subscription Dunning.

Nunca revele ao cliente o motivo real de STOLEN_CARD, LOST_CARD, PICKUP_CARD ou FRAUDULENT. Revelar esses motivos pode alertar um agente fraudulento. Mostre ao cliente uma mensagem genérica de recusa (por exemplo, “Seu cartão foi recusado. Entre em contato com seu banco ou use outro cartão.”) e registre o código específico apenas internamente.Dodo Payments aplica essa regra nas superfícies que controla. Para esses quatro códigos, o checkout, o Customer Portal e os e-mails de dunning exibem uma mensagem genérica de recusa, enquanto o texto destinado ao merchant mantém o motivo real. Aplique a mesma regra em qualquer lugar onde você exibir error_message da API do merchant para um cliente.

Motivos de falha da transação

A tabela a seguir lista todos os códigos de falha, seu tipo de recusa, se o cliente pode resolvê-la, uma descrição e a ação recomendada.

Código de falha	Tipo	Erro do usuário	Descrição	Ação recomendada
`AUTHENTICATION_FAILURE`	Definitiva	Sim	A autenticação falhou durante a transação	Peça ao cliente para tentar novamente e concluir a autenticação 3DS ou usar outro cartão
`AUTHENTICATION_REQUIRED`	Definitiva	Sim	É necessária autenticação adicional para concluir a transação	Solicite que o cliente conclua a autenticação 3DS. Para renovações de assinatura, peça ao cliente para retornar e se autenticar
`AUTHENTICATION_TIMEOUT`	Temporária	Sim	O processo de autenticação expirou	Peça ao cliente para tentar novamente e concluir a autenticação prontamente
`CARD_DECLINED`	Temporária	Não	O banco emissor recusou o cartão sem um motivo específico (recusa genérica)	Peça ao cliente para tentar novamente, entrar em contato com o banco ou usar outro cartão
`CARD_NOT_ACTIVATED`	Temporária	Sim	O titular ainda não ativou o cartão	Peça ao cliente para ativar o cartão com o banco e tentar novamente
`CARD_VELOCITY_EXCEEDED`	Temporária	Sim	Muitas transações foram tentadas em um curto período	Peça ao cliente para aguardar e tentar novamente mais tarde ou entrar em contato com o banco sobre os limites
`CUSTOMER_CANCELLED`	Definitiva	Sim	O cliente cancelou a transação	Permita que o cliente reinicie o checkout quando estiver pronto
`DO_NOT_HONOR`	Definitiva	Não	O banco emissor recusou explicitamente a transação (código ISO 8583 05, não honrar). As redes de cartões tratam isso como definitivo	Peça ao cliente para entrar em contato com o banco. Não tente novamente com o mesmo cartão
`EXPIRED_CARD`	Definitiva	Sim	O cartão expirou	Peça ao cliente para usar um cartão com uma data de validade válida
`FRAUDULENT`	Definitiva	Sim	A transação foi sinalizada como potencialmente fraudulenta	Mostre ao cliente uma mensagem genérica de recusa, sem informar o motivo. Peça que use outro cartão
`GENERIC_DECLINE`	Temporária	Não	A transação foi recusada por um motivo não especificado	Peça ao cliente para entrar em contato com o banco ou tentar outro cartão
`INCORRECT_CVC`	Definitiva	Sim	O CVC informado está incorreto	Peça ao cliente para informar novamente o CVC correto
`INCORRECT_NUMBER`	Definitiva	Sim	O número do cartão foi informado incorretamente	Peça ao cliente para informar novamente o número correto do cartão
`INSUFFICIENT_FUNDS`	Temporária	Sim	A conta não tem fundos suficientes para concluir a transação	Peça ao cliente para usar outro método de pagamento ou tentar novamente quando houver fundos disponíveis
`INVALID_ACCOUNT`	Definitiva	Sim	Os dados da conta fornecidos são inválidos	Peça ao cliente para entrar em contato com o banco ou usar outro cartão
`INVALID_AMOUNT`	Definitiva	Sim	O valor da transação é inválido	Verifique o valor e quaisquer limites de compra com o cliente
`INVALID_CARD_NUMBER`	Definitiva	Sim	O formato do número do cartão é inválido	Peça ao cliente para informar novamente um número de cartão válido
`INVALID_CARD_OWNER`	Definitiva	Sim	As informações do titular do cartão são inválidas	Peça ao cliente para corrigir o nome do titular do cartão
`INVALID_CVC`	Definitiva	Sim	O formato do CVC é inválido	Peça ao cliente para informar novamente um CVC válido
`INVALID_EXPIRY_YEAR`	Definitiva	Sim	O ano de validade do cartão é inválido	Peça ao cliente para informar uma data de validade válida
`INVALID_PIN`	Definitiva	Sim	O PIN informado está incorreto	Peça ao cliente para informar novamente o PIN correto
`INVALID_REQUEST`	Definitiva	Sim	A solicitação de transação contém dados inválidos	Verifique os campos da solicitação de pagamento e reenvie-a com dados válidos
`INVALID_UPI_ID`	Definitiva	Sim	O UPI ID fornecido é inválido	Peça ao cliente para informar um UPI ID válido
`LIMIT_EXCEEDED`	Temporária	Sim	A transação excede o limite do cartão ou da conta	Peça ao cliente para entrar em contato com o banco sobre os limites ou usar outro método
`LIVE_MODE_TEST_CARD`	Definitiva	Sim	Um cartão de teste foi usado em modo live	Use um cartão real. Um cartão de teste sempre falha em modo live
`LOST_CARD`	Definitiva	Sim	O cartão foi reportado como perdido	Mostre ao cliente uma mensagem genérica de recusa, sem informar o motivo. Peça que use outro cartão
`MANDATE_INVALID`	Definitiva	Sim	O mandato de pagamento é inválido	Peça ao cliente para configurar o mandato de pagamento novamente
`MANDATE_REQUIRED`	Definitiva	Sim	É necessário um mandato para esta transação	Configure um mandato e peça ao cliente para autorizá-lo antes da cobrança
`MANDATE_REQUIRED_SYSTEM`	Definitiva	Não	O sistema exige um mandato para este tipo de transação	Conclua o fluxo de configuração do mandato antes da cobrança
`NETWORK_ERROR`	Temporária	Não	Ocorreu um erro de rede durante a transação	Transitório. Tente o pagamento novamente após um breve intervalo
`NETWORK_TIMEOUT`	Temporária	Não	A solicitação de rede expirou	Transitório. Tente o pagamento novamente após um breve intervalo
`ORDER_ALREADY_EXISTS`	Definitiva	Não	Já existe um pedido para esta transação (criação de pedido duplicada)	Verifique o status do pedido existente antes de tentar novamente. Entre em contato com o suporte se o problema persistir
`ORDER_CREATION_FAILED`	Temporária	Não	Não foi possível criar o pedido da transação	Erro transitório ou do sistema. Tente o pagamento novamente e entre em contato com o suporte se o problema persistir
`PAYMENT_METHOD_PROVIDER_DECLINED`	Definitiva	Sim	O provedor do método de pagamento recusou a transação	Peça ao cliente para entrar em contato com o provedor ou usar outro método de pagamento
`PAYMENT_METHOD_UNSUPPORTED`	Definitiva	Sim	O método de pagamento não é compatível com esta transação	Peça ao cliente para usar um método de pagamento compatível
`PICKUP_CARD`	Definitiva	Sim	O cartão foi reportado como perdido ou roubado e sinalizado para recolhimento	Mostre ao cliente uma mensagem genérica de recusa, sem informar o motivo. Peça que use outro cartão
`PROCESSING_ERROR`	Temporária	Não	Ocorreu um erro ao processar a transação	Transitório. Tente o pagamento novamente. Se o problema persistir, peça ao cliente para entrar em contato com o banco
`PROVIDER_UNSUPPORTED`	Definitiva	Não	O provedor de pagamento não oferece suporte a este tipo de transação	Peça ao cliente para usar outro método de pagamento
`REENTER_TRANSACTION`	Temporária	Sim	A transação precisa ser inserida novamente	Peça ao cliente para tentar o pagamento novamente
`REVOCATION_OF_AUTHORIZATION`	Definitiva	Sim	A autorização da transação foi revogada	Peça ao cliente para usar outro método de pagamento
`STOLEN_CARD`	Definitiva	Sim	O cartão foi reportado como roubado	Mostre ao cliente uma mensagem genérica de recusa, sem informar o motivo. Peça que use outro cartão
`SUBSCRIPTION_NOT_ACTIVE`	Definitiva	Não	A assinatura não está ativa, portanto, não foi possível processar a cobrança recorrente	Reative a assinatura (por exemplo, atualizando o método de pagamento) antes de tentar fazer a cobrança novamente
`TRANSACTION_NOT_ALLOWED`	Temporária	Sim	A transação não é permitida para este cartão ou conta	Tente novamente após um intervalo. Se continuar falhando, peça ao cliente para entrar em contato com o banco para permitir este tipo de transação ou usar outro cartão
`TRANSACTION_NOT_APPROVED`	Temporária	Sim	A transação não foi aprovada	Tente novamente após um intervalo. Se continuar falhando, peça ao cliente para entrar em contato com o banco ou tentar outro cartão
`TRY_AGAIN_LATER`	Temporária	Não	A transação deve ser tentada novamente mais tarde	Transitório. Tente o pagamento novamente mais tarde
`UNKNOWN_ERROR`	Temporária	Não	Ocorreu um erro desconhecido	Tente o pagamento novamente. Se o problema persistir, entre em contato com o suporte

Erro do usuário indica se o cliente pode resolver a recusa. Yes significa que o cliente pode corrigir o problema, por exemplo, informando os dados corretos do cartão. No significa que um problema no sistema ou uma restrição do banco causou a recusa, e o cliente não pode resolvê-la diretamente.

Um banco emissor também pode recusar um cartão porque seu próprio motor de risco identifica o titular do cartão como de alto risco, independentemente do comerciante ou dos detalhes da transação. Essas recusas geralmente aparecem como códigos genéricos, como DO_NOT_HONOR, GENERIC_DECLINE, CARD_DECLINED, TRANSACTION_NOT_APPROVED ou FRAUDULENT. O banco não compartilha o motivo específico, e nem Dodo Payments nem o comerciante podem reverter a decisão. Peça ao cliente que entre em contato com o banco para resolver o alerta ou que use outro cartão ou método de pagamento.

Tratamento programático de falhas

Leia error_code do webhook payment.failed ou do objeto de pagamento, associe-o à ação recomendada na tabela e decida se deve tentar novamente. Para renovações de assinatura, Dodo Payments tenta novamente as recusas temporárias por você. Consulte Subscription Payment Retries. Para erros de API e de lógica de negócios que não são recusas de cartão, como PAYMENT_NOT_SUCCEEDED ou REFUND_WINDOW_EXPIRED, consulte a referência de Error Codes.

Relacionados

Handle Payment Failures

Guia completo para detectar, exibir e tentar novamente pagamentos com falha.

Error Codes

Códigos de erro da API e da lógica de negócios para falhas que não são recusas.

Subscription Payment Retries

Tentativas automáticas que recuperam recusas temporárias em renovações de assinaturas.

Subscription Dunning

Sequências de e-mails que recuperam recusas permanentes ao solicitar a atualização do meio de pagamento.

Suporte

Para obter mais ajuda com falhas de transação ou problemas de integração, entre em contato com a equipe de suporte pelo endereço support@dodopayments.com.

API Reference

Checkout Sessions

Payments

Subscriptions

Discounts

Licenses

Entitlements

Customers

Customer Wallets

Products

Localized Pricing

Addons

Credit Entitlements

Meters

Usage Events

Refunds

Disputes

Payouts

Balance Ledger

Moderation

Brands

Webhooks

Miscellaneous

Product Collections

Visão Geral

Texto para o Merchant vs. Texto para o Customer

Handle Payment Failures

Recusas temporárias e permanentes

Motivos de falha da transação

Tratamento programático de falhas

Relacionados

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Suporte

​Visão Geral

​Texto para o Merchant vs. Texto para o Customer

Handle Payment Failures

​Recusas temporárias e permanentes

​Motivos de falha da transação

​Tratamento programático de falhas

​Relacionados

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

​Suporte

Visão Geral

Texto para o Merchant vs. Texto para o Customer

Recusas temporárias e permanentes

Motivos de falha da transação

Tratamento programático de falhas

Relacionados

Suporte