Gerenciar Falhas de Pagamento

Quando um pagamento falha, o Dodo Payments informa por quê através de um error_code padronizado e um error_message legível para humanos. Este guia mostra como ler esses campos, decidir se vale a pena tentar novamente e recuperar o pagamento sem expor informações sensíveis aos clientes.

Como o Dodo Payments Relata uma Falha

Todo pagamento falho — seja uma compra única ou uma renovação de assinatura — possui os mesmos campos de falha no objeto de pagamento:

Field	Type	Description
`status`	string	`failed` para um pagamento com falha. Outros estados que não indicam sucesso incluem `cancelled`, `requires_customer_action` e `requires_payment_method`.
`error_code`	string \| null	O motivo padronizado da falha, por exemplo, `INSUFFICIENT_FUNDS` ou `PROCESSING_ERROR`. Consulte a referência de Transaction Failures para ver a lista completa.
`error_message`	string \| null	Uma explicação da falha em linguagem natural, escrita para você, e não para o cliente. Para um `error_code` padronizado, trata-se de um título acompanhado da ação recomendada, não do texto bruto do processador.
`retry_attempt`	integer	`0` da cobrança original. `1` ou superior identifica uma nova tentativa agendada de renovação de assinatura.

error_code e error_message são null até que um pagamento realmente falhe. Sempre verifique primeiro status, depois leia os campos de erro.

error_message da merchant API é um texto voltado ao merchant. Ele pode indicar o motivo real de uma recusa, inclusive motivos relacionados a fraude; portanto, nunca o exiba diretamente ao cliente. Mapeie error_code para uma mensagem segura para o cliente, conforme mostrado em Exibir erros aos clientes com segurança.

O webhook `payment.failed`

A maneira mais confiável de detectar uma falha é o webhook payment.failed. O evento inclui o objeto de pagamento completo em data:

payment.failed payload

{
  "business_id": "bus_P3SXLcppjXgagmHS",
  "type": "payment.failed",
  "timestamp": "2025-08-04T05:36:41.609359Z",
  "data": {
    "payload_type": "Payment",
    "payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
    "status": "failed",
    "error_code": "PROCESSING_ERROR",
    "error_message": "An error occurred while processing your card. Try again in a little bit.",
    "retry_attempt": 0,
    "subscription_id": null,
    "currency": "USD",
    "total_amount": 400,
    "payment_method": "card",
    "card_last_four": "0119",
    "card_network": "VISA",
    "payment_link": "https://test.checkout.dodopayments.com/cbq",
    "customer": {
      "customer_id": "cus_8VbC6JDZzPEqfB",
      "email": "test@acme.com",
      "name": "Test user"
    }
  }
}

Um handler mínimo lê error_code e define o fluxo com base nele:

import { Webhook } from "standardwebhooks";
import express from "express";

const app = express();
// Mount the raw body parser so the exact payload is available for verification
app.use(express.raw({ type: "application/json" }));

const webhook = new Webhook(process.env.DODO_PAYMENTS_WEBHOOK_KEY);

app.post("/webhooks/dodo", async (req, res) => {
  // Verify the signature against the raw body before trusting the payload
  const payload = req.body.toString();
  await webhook.verify(payload, req.headers);

  const event = JSON.parse(payload);

  if (event.type === "payment.failed") {
    const payment = event.data;

    console.log(
      `Payment ${payment.payment_id} failed: ${payment.error_code} (${payment.error_message})`
    );

    if (payment.subscription_id) {
      // Subscription renewal — Dodo retries soft declines for you
      await flagSubscriptionPaymentIssue(payment.subscription_id, payment.error_code);
    } else {
      // One-time payment — prompt the customer to try again
      await notifyCustomerOfFailedPayment(payment.customer.customer_id, payment.error_code);
    }
  }

  res.json({ received: true });
});

import os
from fastapi import FastAPI, Request
from standardwebhooks import Webhook

app = FastAPI()
webhook = Webhook(os.environ["DODO_PAYMENTS_WEBHOOK_KEY"])

@app.post("/webhooks/dodo")
async def handle_webhook(request: Request):
    # Verify the signature before trusting the payload
    payload = await request.body()
    webhook.verify(payload, dict(request.headers))

    event = await request.json()

    if event["type"] == "payment.failed":
        payment = event["data"]

        print(
            f"Payment {payment['payment_id']} failed: "
            f"{payment['error_code']} ({payment['error_message']})"
        )

        if payment["subscription_id"]:
            # Subscription renewal — Dodo retries soft declines for you
            flag_subscription_payment_issue(payment["subscription_id"], payment["error_code"])
        else:
            # One-time payment — prompt the customer to try again
            notify_customer_of_failed_payment(payment["customer"]["customer_id"], payment["error_code"])

    return {"received": True}

Sempre verifique a assinatura do webhook antes de processá-lo. Consulte o guia de Webhooks para ver a configuração completa, incluindo a verificação de assinatura e a idempotência.

Decida se deve tentar novamente: recusas temporárias vs. permanentes

O error_code informa se vale a pena tentar novamente com o mesmo método de pagamento.

Decline type	What it means	What to do
Recusa temporária	Temporária ou corrigível (por exemplo, `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`).	Tentar novamente — após um intervalo ou depois que o cliente corrigir os dados — pode funcionar.
Recusa permanente	Definitiva (por exemplo, `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`).	Não tente novamente com o mesmo cartão. Peça ao cliente outro método de pagamento.

A referência de Transaction Failures lista o tipo de recusa e a ação recomendada para cada error_code.

Como lidar com falhas no checkout e na renovação

A forma de recuperação depende de o cliente estar presente.

At checkout (customer present)
On subscription renewal (customer not present)

O cliente está realizando o checkout ativamente. Exiba uma mensagem clara e permita que ele tente novamente imediatamente ou use outro cartão.

requires_payment_method — o cliente nunca forneceu um método de pagamento: não inseriu os dados do cartão ou recebeu uma solicitação para informá-los, mas não tomou nenhuma ação. Geralmente, isso é um abandono no checkout, não uma recusa — reengaje o cliente para concluir o pagamento (consulte Recuperação de carrinho abandonado).
requires_customer_action — é necessária uma autenticação adicional (como 3DS); peça ao cliente que a conclua. Consulte Como lidar com o 3D Secure.

O cliente não está presente, portanto você não pode solicitar uma ação em tempo real. Quando uma renovação falha, a assinatura é movida para on_hold e subscription.on_hold é acionado.

Recusas temporárias são tentadas novamente automaticamente por Subscription Payment Retries.
Recusas permanentes (e tentativas esgotadas) são recuperadas da melhor forma com Subscription Dunning, que envia um e-mail ao cliente solicitando a atualização do método de pagamento.

Consulte o guia de integração de assinaturas para ver o fluxo completo de suspensão → reativação.

Tentar novamente um pagamento com falha

Assinaturas: ative Subscription Payment Retries para recuperar recusas temporárias sem trabalho de integração. Você também pode acionar a recuperação fazendo com que o cliente atualize o método de pagamento por meio da Update Payment Method API, que cobra quaisquer valores pendentes.
Pagamentos avulsos: reenvie o checkout ou payment_link para que o cliente possa tentar novamente com outro método. Não há tentativa automática para pagamentos avulsos.

Não tente novamente recusas permanentes com o mesmo cartão. As bandeiras de cartão podem sinalizar recusas repetidas como abuso, prejudicando sua taxa de autorização.

Exibir erros aos clientes com segurança

Exiba uma mensagem amigável para os clientes — nunca o error_code bruto e nunca o error_message voltado ao merchant.

Nas superfícies controladas pela Dodo Payments — checkout, o Customer Portal e os e-mails de cobrança — esse mapeamento já é feito para você, incluindo o fallback para uma mensagem genérica em caso de recusas relacionadas a fraude. Você só precisa do mapeamento abaixo quando exibir falhas no seu próprio produto.

Customer-facing messaging

const CUSTOMER_MESSAGES = {
  INSUFFICIENT_FUNDS: "Your card has insufficient funds. Please use another card.",
  EXPIRED_CARD: "Your card has expired. Please use a card with a valid expiry date.",
  INCORRECT_CVC: "The security code (CVC) is incorrect. Please re-enter it.",
};

function customerMessage(errorCode) {
  // Sensitive declines must never reveal the real reason
  const SENSITIVE = ["STOLEN_CARD", "LOST_CARD", "PICKUP_CARD", "FRAUDULENT"];
  if (SENSITIVE.includes(errorCode)) {
    return "Your card was declined. Please contact your bank or use another card.";
  }
  return CUSTOMER_MESSAGES[errorCode] ?? "Your payment could not be processed. Please try another card.";
}

Nunca revele o motivo real de STOLEN_CARD, LOST_CARD, PICKUP_CARD ou FRAUDULENT. Exibir essas informações pode alertar um agente fraudulento. Mostre uma mensagem genérica de recusa e registre internamente apenas o error_code específico.

Relacionados

Transaction Failures

Cada código de recusa, seu tipo e a ação recomendada.

Error Codes

Erros de API e de lógica de negócios que não são recusas de cartão.

Subscription Payment Retries

Recuperação automática de recusas temporárias em renovações de assinaturas.

Subscription Dunning

Sequências de e-mails que recuperam recusas permanentes.

Payment Webhooks

Esquema completo do payload para eventos de pagamento.

Testing Failures

Cartões de teste que simulam recusas e falhas de renovação.

Integration Guides

Billing Deconstructions

Cookbooks

Como o Dodo Payments Relata uma Falha

O webhook `payment.failed`

Decida se deve tentar novamente: recusas temporárias vs. permanentes

Como lidar com falhas no checkout e na renovação

Tentar novamente um pagamento com falha

Exibir erros aos clientes com segurança

Relacionados

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Como o Dodo Payments Relata uma Falha

​O webhook payment.failed

​Decida se deve tentar novamente: recusas temporárias vs. permanentes

​Como lidar com falhas no checkout e na renovação

​Tentar novamente um pagamento com falha

​Exibir erros aos clientes com segurança

​Relacionados

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Como o Dodo Payments Relata uma Falha

O webhook `payment.failed`

Decida se deve tentar novamente: recusas temporárias vs. permanentes

Como lidar com falhas no checkout e na renovação

Tentar novamente um pagamento com falha

Exibir erros aos clientes com segurança

Relacionados