> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dodopayments.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Falhas de Transação
> Entenda cada código de falha de transação do Dodo Payments, se é uma recusa suave ou dura, e a ação recomendada para recuperar o pagamento.
## 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.
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](/features/recovery/payment-retries), enquanto recusas duras encerram imediatamente a cadeia de tentativas e são melhor tratadas com [Recuperação de Assinatura](/features/recovery/subscription-dunning).
**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](/features/recovery/payment-retries).
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](/api-reference/error-codes).
## Relacionado
Guia completo para detectar, identificar e tentar novamente pagamentos falhos.
Códigos de erro de API e lógica de negócios para falhas que não são recusas.
Tentativas automáticas que recuperam recusas suaves em renovações de assinatura.
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](mailto:support@dodopayments.com).