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, opayment.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 escrita para você, o merchant. Quandoerror_codeé um dos códigos padronizados abaixo, este é um título acompanhado da ação recomendada, em vez do texto bruto do processador de pagamentos.retry_attempt—0para a cobrança original,1ou superior para cada tentativa de renovação agendada da assinatura.
Texto para o Merchant vs. Texto para o Customer
Cada código de falha padronizado corresponde a duas mensagens diferentes, para que o público certo veja o nível adequado de detalhes:O Customer Portal retorna o texto voltado ao customer em
error_message, enquanto a API do merchant retorna o texto voltado ao merchant para o mesmo pagamento. O error_code é idêntico em ambos.Handle Payment Failures
Um guia de desenvolvimento passo a passo para ler esses códigos de webhooks e da API, exibi-los para os customers e decidir quando tentar novamente.
Recusas temporárias e permanentes
Todo código de falha pertence a uma de duas categorias. Essa distinção determina se você deve tentar novamente com o mesmo meio de pagamento ou pedir ao customer que use outro.
Para renovações de assinaturas, Dodo Payments aplica essa distinção automaticamente: recusas temporárias são tentadas novamente pelo Subscription Payment Retries, enquanto recusas permanentes encerram imediatamente a cadeia de tentativas e são tratadas da melhor forma com Subscription Dunning.
Motivos de falha da transação
A tabela a seguir lista todos os códigos de falha, seu tipo de recusa, se o customer pode resolvê-la, uma descrição e a ação recomendada.Erro do usuário indica se a recusa do pagamento pode ser resolvida pelo customer. Quando
Yes, o customer pode tomar medidas para corrigir o problema (por exemplo, inserir os dados corretos do cartão). Quando No, a recusa é causada por problemas no sistema ou restrições do banco que o customer não pode resolver diretamente.Um cartão também pode ser recusado quando o próprio mecanismo de risco do banco emissor sinaliza o titular como um customer de alto risco — independentemente do merchant 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 Dodo Payments nem o merchant podem substituir a decisão. Peça ao customer para entrar em contato com o banco a fim de resolver a sinalização ou usar outro cartão ou meio de pagamento.Tratamento programático de falhas
Leiaerror_code do webhook payment.failed ou do objeto de pagamento, associe-o à ação recomendada acima e decida se deve tentar novamente. Para renovações de assinaturas, recusas temporárias são tentadas novamente automaticamente para você — consulte Subscription Payment Retries.
Para erros no nível da API e da 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 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.