Falhas de Transação - Dodo Payments Documentation

Visão Geral

O Dodo Payments retorna uma razão detalhada de falha sempre que uma tentativa de pagamento é mal sucedida. Esses motivos são padronizados entre métodos e provedores de pagamento, permitindo que você implemente um tratamento consistente em sua aplicação. Quando um pagamento falha, o payment.failed webhook e o objeto de pagamento expõem:

error_code — um motivo de falha padronizado da tabela abaixo.
error_message — uma explicação legível para humanos.
retry_attempt — 0 para a cobrança original, 1 ou superior para cada tentativa de renovação de assinatura agendada.

Entender esses motivos de falha permite dar um feedback claro aos clientes, decidir se uma nova tentativa vale a pena, e recuperar mais receita.

Handle Payment Failures

Um guia passo a passo para desenvolvedores sobre como ler esses códigos de webhooks e da API, apresentá-los aos clientes, e decidir quando tentar novamente.

Recusas Suaves vs. Duras

Cada código de falha se encaixa em uma das duas categorias. Essa distinção determina se você deve tentar novamente com o mesmo método de pagamento ou pedir ao cliente um novo.

Tipo de Recusa	O que significa	O que fazer	Exemplos
Recusa suave	Temporária ou corrigível — o mesmo cartão pode ter sucesso em uma tentativa posterior ou uma vez que o cliente corrige seu erro.	Seguro para tentar novamente (depois de um atraso, ou uma vez que o cliente corrige seus detalhes).	`INSUFFICIENT_FUNDS`, `GENERIC_DECLINE`, `CARD_VELOCITY_EXCEEDED`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `NETWORK_TIMEOUT`, `TRY_AGAIN_LATER`
Recusa dura	Terminal — tentar o mesmo cartão não mudará o resultado.	Não tentar novamente o mesmo cartão. Peça ao cliente para usar outro método de pagamento ou contacte seu banco.	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`

Para renovações de assinatura, o Dodo Payments aplica essa distinção automaticamente: recusas suaves são tentadas novamente por Recuperações de Pagamento de Assinatura, enquanto recusas duras encerram imediatamente a cadeia de tentativas e são melhor tratadas com Recuperação de Assinatura.

Nunca revele a verdadeira razão para STOLEN_CARD, LOST_CARD, PICKUP_CARD, ou FRAUDULENT para o cliente. Apresentar esses motivos pode alertar um ator fraudulento. Sempre mostre ao cliente uma mensagem genérica de recusa (por exemplo, “Seu cartão foi recusado. Por favor, entre em contato com seu banco ou use outro cartão.”) e apenas registre o código específico internamente.

Motivos de Falha de Transação

A seguinte tabela lista cada código de falha, seu tipo de recusa, se o cliente pode resolvê-lo, uma descrição e a ação recomendada.

Código de Falha	Tipo	Erro do Usuário	Descrição	Ação Recomendada
`AUTHENTICATION_FAILURE`	Suave	Sim	Autenticação falhou durante a transação	Peça ao cliente para tentar novamente e completar a autenticação 3DS, ou use outro cartão
`AUTHENTICATION_REQUIRED`	Suave	Sim	Autenticação adicional é necessária para completar a transação	Solicite que o cliente complete a autenticação 3DS. Para renovações de assinatura, peça ao cliente para retornar e autenticar
`AUTHENTICATION_TIMEOUT`	Suave	Sim	O processo de autenticação expirou	Peça ao cliente para tentar novamente e completar a autenticação rapidamente
`CARD_DECLINED`	Suave	Não	O cartão foi recusado pelo banco emissor sem uma razão específica (recusa genérica)	Peça ao cliente para tentar novamente, entrar em contato com seu banco, ou usar outro cartão
`CARD_NOT_ACTIVATED`	Suave	Sim	O cartão não foi ativado pelo titular do cartão	Peça ao cliente para ativar o cartão com seu banco e tentar novamente
`CARD_VELOCITY_EXCEEDED`	Suave	Sim	Muitas transações foram tentadas em um curto período	Peça ao cliente para aguardar e tentar mais tarde, ou entrar em contato com seu banco sobre limites
`CUSTOMER_CANCELLED`	Suave	Sim	O cliente cancelou a transação	Deixe o cliente reiniciar o checkout quando estiver pronto
`DO_NOT_HONOR`	Dura	Não	O banco emissor recusou explicitamente a transação (código ISO 8583 05 — não honrar); as redes tratam isso como terminal	Peça ao cliente para entrar em contato com seu banco; não tente o mesmo cartão novamente
`EXPIRED_CARD`	Dura	Sim	O cartão está expirado	Peça ao cliente para usar um cartão com data de validade válida
`FRAUDULENT`	Dura	Sim	A transação foi sinalizada como potencialmente fraudulenta	Mostre ao cliente uma mensagem genérica de recusa — não revele o motivo. Peça para usar outro cartão
`GENERIC_DECLINE`	Suave	Não	A transação foi recusada por uma razão não especificada	Peça ao cliente para entrar em contato com seu banco ou tentar outro cartão
`INCORRECT_CVC`	Suave	Sim	O código CVC fornecido estava incorreto	Peça ao cliente para inserir o CVC correto novamente
`INCORRECT_NUMBER`	Suave	Sim	O número do cartão foi digitado incorretamente	Peça ao cliente para inserir o número do cartão correto novamente
`INSUFFICIENT_FUNDS`	Suave	Sim	A conta não possui fundos suficientes para completar a transação	Peça ao cliente para usar outro método de pagamento ou tentar novamente quando os fundos estiverem disponíveis
`INVALID_ACCOUNT`	Dura	Sim	Os detalhes da conta fornecidos são inválidos	Peça ao cliente para entrar em contato com seu banco ou usar outro cartão
`INVALID_AMOUNT`	Suave	Sim	O valor da transação é inválido	Verifique o valor e quaisquer limites de compra com o cliente
`INVALID_CARD_NUMBER`	Suave	Sim	O formato do número do cartão é inválido	Peça ao cliente para inserir novamente um número de cartão válido
`INVALID_CARD_OWNER`	Suave	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`	Suave	Sim	O formato CVC é inválido	Peça ao cliente para inserir novamente um CVC válido
`INVALID_EXPIRY_YEAR`	Suave	Sim	O ano de validade do cartão é inválido	Peça ao cliente para inserir uma data de validade válida
`INVALID_PIN`	Suave	Sim	O PIN fornecido está incorreto	Peça ao cliente para inserir novamente o PIN correto
`INVALID_REQUEST`	Suave	Sim	A solicitação de transação contém dados inválidos	Verifique os campos da solicitação de pagamento e reenvie com dados válidos
`INVALID_UPI_ID`	Suave	Sim	O ID UPI fornecido é inválido	Peça ao cliente para inserir um ID UPI válido
`LIMIT_EXCEEDED`	Suave	Sim	A transação excede o limite do cartão ou da conta	Peça ao cliente para entrar em contato com seu banco sobre limites, ou usar outro método
`LIVE_MODE_TEST_CARD`	Dura	Sim	Um cartão de teste foi usado no modo ao vivo	Use um cartão real — tentar novamente o cartão de teste sempre falhará no modo ao vivo
`LOST_CARD`	Dura	Sim	O cartão foi relatado como perdido	Mostre ao cliente uma mensagem genérica de recusa — não revele o motivo. Peça para usar outro cartão
`MANDATE_INVALID`	Suave	Sim	O mandato de pagamento é inválido	Peça ao cliente para configurar o mandato de pagamento novamente
`MANDATE_REQUIRED`	Suave	Sim	Um mandato é necessário para esta transação	Configure um mandato e peça ao cliente para autorizá-lo antes de cobrar
`MANDATE_REQUIRED_SYSTEM`	Dura	Não	O sistema requer um mandato para este tipo de transação	Certifique-se de que o fluxo de configuração do mandato seja concluído antes de cobrar
`NETWORK_ERROR`	Suave	Não	Um erro de rede ocorreu durante a transação	Transitório — tente o pagamento novamente após um curto período
`NETWORK_TIMEOUT`	Suave	Não	O pedido de rede expirou	Transitório — tente o pagamento novamente após um curto período
`ORDER_ALREADY_EXISTS`	Suave	Não	Já existe um pedido para essa transação (criação de pedido duplicado)	Verifique o status do pedido existente antes de tentar novamente; entre em contato com o suporte se persistir
`ORDER_CREATION_FAILED`	Suave	Não	Falha ao criar o pedido para a transação	Erro transitório/sistema — tente o pagamento novamente; entre em contato com o suporte se persistir
`PAYMENT_METHOD_PROVIDER_DECLINED`	Dura	Sim	O provedor do método de pagamento recusou a transação	Peça ao cliente para entrar em contato com seu provedor ou usar outro método de pagamento
`PAYMENT_METHOD_UNSUPPORTED`	Dura	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`	Dura	Sim	O cartão foi relatado como perdido ou roubado e sinalizado para coleta	Mostre ao cliente uma mensagem genérica de recusa — não revele o motivo. Peça para usar outro cartão
`PROCESSING_ERROR`	Suave	Não	Ocorreu um erro ao processar a transação	Transitório — tente o pagamento novamente; se persistir, peça ao cliente para entrar em contato com seu banco
`PROVIDER_UNSUPPORTED`	Dura	Não	O provedor de pagamento não suporta este tipo de transação	Peça ao cliente para usar outro método de pagamento
`REENTER_TRANSACTION`	Suave	Sim	A transação precisa ser reentrada	Peça ao cliente para tentar o pagamento novamente
`REVOCATION_OF_AUTHORIZATION`	Dura	Sim	A autorização para a transação foi revogada	Peça ao cliente para usar outro método de pagamento
`STOLEN_CARD`	Dura	Sim	O cartão foi relatado como roubado	Mostre ao cliente uma mensagem genérica de recusa — não revele o motivo. Peça para usar outro cartão
`SUBSCRIPTION_NOT_ACTIVE`	Dura	Não	A assinatura não está ativa, então a cobrança recorrente não pôde ser processada	Reative a assinatura (por exemplo, atualizando o método de pagamento) antes de tentar a cobrança novamente
`TRANSACTION_NOT_ALLOWED`	Dura	Sim	A transação não é permitida para este cartão ou conta	Peça ao cliente para entrar em contato com seu banco para permitir este tipo de transação, ou usar outro cartão
`TRANSACTION_NOT_APPROVED`	Dura	Sim	A transação não foi aprovada	Peça ao cliente para entrar em contato com seu banco ou tentar outro cartão
`TRY_AGAIN_LATER`	Suave	Não	A transação deve ser tentada novamente mais tarde	Transitório — tente o pagamento novamente mais tarde
`UNKNOWN_ERROR`	Suave	Não	Ocorreu um erro desconhecido	Tente o pagamento novamente; se persistir, entre em contato com o suporte

Erro do Usuário indica se a recusa de pagamento pode ser resolvida pelo cliente. Quando Yes, o cliente pode tomar uma ação para resolver o problema (por exemplo, inserir detalhes corretos do cartão). Quando No, a recusa é devido a questões de nível de sistema ou restrições bancárias que o cliente não pode resolver diretamente.

Um cartão também pode ser recusado quando o próprio mecanismo de risco do banco emissor classifica o portador do cartão como um cliente 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. Nesses casos, o banco não compartilha o motivo específico, e nem a Dodo Payments nem o comerciante podem anular a decisão. Peça ao cliente para entrar em contato com seu banco para resolver a sinalização, ou use um cartão ou método de pagamento diferente.

Lidando com Falhas Programaticamente

Leia error_code do webhook payment.failed ou do objeto de pagamento, mapeie para a ação recomendada acima e decida se deve tentar novamente. Para renovações de assinaturas, recusas suaves são tentadas novamente automaticamente — veja Tentativas de Pagamento de Assinatura. Para erros de nível de API e lógica de negócios (como PAYMENT_NOT_SUCCEEDED ou REFUND_WINDOW_EXPIRED) que não são recusas de cartão, consulte a referência de Códigos de Erro.

Relacionado

Handle Payment Failures

Guia completo para detectar, identificar e tentar novamente pagamentos falhos.

Error Codes

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

Subscription Payment Retries

Tentativas automáticas que recuperam recusas suaves em renovações de assinatura.

Subscription Dunning

Sequências de e-mails que recuperam recusas duras, solicitando a atualização do método de pagamento.

Suporte

Para ajuda adicional com falhas de transações ou problemas de integração, entre em contato com nossa equipe de suporte em support@dodopayments.com.

​Visão Geral

Handle Payment Failures

​Recusas Suaves vs. Duras

​Motivos de Falha de Transação

​Lidando com Falhas Programaticamente

​Relacionado

Handle Payment Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

​Suporte

Visão Geral

Recusas Suaves vs. Duras

Motivos de Falha de Transação

Lidando com Falhas Programaticamente

Relacionado

Suporte