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 para humanos.retry_attempt—0para a cobrança original,1ou superior para cada tentativa de renovação de assinatura agendada.
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 |
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.Manipulando Falhas Programaticamente
Leiaerror_code do payment.failed webhook ou do objeto de pagamento, mapeie para a ação recomendada acima, e decida se deve tentar novamente. Para renovações de assinatura, recusas suaves são tentadas novamente automaticamente — veja Recuperações de Pagamento de Assinatura.
Para erros de nível API e lógica de negócios (como PAYMENT_NOT_SUCCEEDED ou REFUND_WINDOW_EXPIRED) que não são recusas de pagamento, veja a referência Códigos de Erro.
Relacionados
Handle Payment Failures
Guia completo para detectar, apresentar e tentar novamente pagamentos falhos.
Error Codes
Códigos de erro de API e lógica de negócios para falhas não relacionadas a recusa.
Subscription Payment Retries
Tentativas automáticas que recuperam recusas suaves em renovações de assinatura.
Subscription Dunning
Sequências de email que recuperam recusas duras solicitando uma atualização de método de pagamento.