Gerenciar Falhas de Pagamento

Quando um pagamento falha, o Dodo Payments fornece um error_code padronizado e uma mensagem error_message legível. Este guia mostra como ler esses campos, decidir se deve tentar novamente e recuperar o pagamento com segurança.

Como o Dodo Payments Relata uma Falha

Todo pagamento com falha contém estes campos no objeto de pagamento:

Campo	Tipo	Descrição
`status`	string	`failed` para um pagamento com falha. Outros estados que não indicam sucesso: `cancelled`, `requires_customer_action`, `requires_payment_method`.
`error_code`	string \| null	Motivo de falha padronizado, por exemplo, `INSUFFICIENT_FUNDS` ou `PROCESSING_ERROR`. Consulte Transaction Failures para ver a lista completa.
`error_message`	string \| null	Explicação voltada ao comerciante, com a ação recomendada. Não deve ser exibida aos clientes.
`retry_attempt`	integer	`0` para a cobrança original. `1` ou superior para novas tentativas de renovação de assinatura agendadas.

error_code e error_message são null até que um pagamento falhe. Sempre verifique status primeiro.

error_message é voltado ao comerciante e pode revelar motivos relacionados a fraude. Nunca o exiba aos clientes. Em vez disso, mapeie error_code para uma mensagem segura para o cliente (consulte Exibir erros aos clientes com segurança).

O webhook `payment.failed`

O webhook payment.failed é a maneira mais confiável de detectar uma falha. O evento encapsula 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 direciona 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 payment. If Payment Retries is on, Dodo retries failed renewals.
      // On-demand charges are never retried automatically: handle those yourself.
      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 payment. If Payment Retries is on, Dodo retries failed renewals.
            # On-demand charges are never retried automatically: handle those yourself.
            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.

Tipo de recusa	Exemplos	Ação
Recusa temporária	`INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`	Tente novamente após um intervalo ou quando o cliente corrigir os dados informados.
Recusa permanente	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`	Não tente novamente com o mesmo cartão. Peça ao cliente um método de pagamento diferente.

Consulte Transaction Failures para ver a lista completa de tipos de recusa e ações recomendadas.

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á finalizando a compra. Exiba uma mensagem clara e permita que ele tente novamente ou use outro cartão.

requires_payment_method — o cliente nunca forneceu um método de pagamento. Geralmente isso indica abandono durante o checkout, não uma recusa. Incentive o cliente a concluir o pagamento (consulte Recuperação de carrinho abandonado).
requires_customer_action — é necessária autenticação adicional (como 3DS). Peça ao cliente que a conclua. Consulte 3D Secure.

O cliente não está presente. Quando uma renovação falha, a assinatura passa para on_hold e subscription.on_hold é acionado. Se sua empresa tiver um período de carência, ela passa primeiro para past_due (subscription.past_due) e mantém o acesso até o fim do período de carência.

Recusas temporárias são tentadas novamente automaticamente se você ativar Tentativas novamente de pagamento de assinaturas (desativado por padrão). As novas tentativas abrangem apenas renovações agendadas, não cobranças sob demanda.
Recusas permanentes (e novas tentativas esgotadas) em renovações agendadas são recuperadas com Subscription Dunning, que envia um e-mail ao cliente para que ele atualize o método de pagamento. Para falhas em cobranças sob demanda, consulte Assinaturas sob demanda.

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 automaticamente. Para tentar novamente imediatamente, em vez de aguardar o agendamento, use Manual Payment Retry no dashboard ou na API. Você também pode iniciar a recuperação fazendo com que o cliente atualize o método de pagamento pela 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 um método diferente. Não há novas tentativas automáticas para pagamentos avulsos.

Não tente novamente recusas permanentes usando o mesmo cartão. As bandeiras de cartão sinalizam recusas repetidas como abusivas, o que prejudica sua taxa de autorização.

Exibir erros aos clientes com segurança

Mostre uma mensagem amigável aos clientes, nunca o error_code bruto nem o error_message voltado ao comerciante.

Nas interfaces controladas pelo Dodo Payments (checkout, Customer Portal, e-mails de cobrança), esse mapeamento já é feito para você, incluindo o fallback para uma mensagem genérica em recusas relacionadas a fraude. Você só precisa usar o 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 esses motivos pode alertar um agente fraudulento. Mostre uma mensagem genérica de recusa e registre o error_code específico apenas internamente.

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ócio 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