Gestionar Fallos de Pago

Cuando falla un pago, Dodo Payments proporciona un error_code estandarizado y un error_message legible. Esta guía muestra cómo leer esos campos, decidir si se debe reintentar y recuperar el pago de forma segura.

Cómo Dodo Payments Informa un Fallo

Cada pago fallido incluye estos campos en el objeto de pago:

Campo	Tipo	Descripción
`status`	string	`failed` para un pago fallido. Otros estados que no indican éxito: `cancelled`, `requires_customer_action`, `requires_payment_method`.
`error_code`	string \| null	Motivo de fallo estandarizado, por ejemplo, `INSUFFICIENT_FUNDS` o `PROCESSING_ERROR`. Consulta Transaction Failures para ver la lista completa.
`error_message`	string \| null	Explicación dirigida al merchant con la acción recomendada. No debe mostrarse a los clientes.
`retry_attempt`	integer	`0` del cargo original. `1` o superior para reintentos de renovaciones de suscripción programadas.

error_code y error_message son null hasta que falla un pago. Comprueba siempre status primero.

error_message está dirigido al merchant y puede revelar motivos relacionados con el fraude. Nunca lo muestres a los clientes. En su lugar, asigna error_code a un texto seguro para el cliente (consulta Mostrar errores a los clientes de forma segura).

El webhook de `payment.failed`

El webhook payment.failed es la forma más fiable de detectar un fallo. El evento incluye el objeto de pago completo en 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"
    }
  }
}

Un handler mínimo lee error_code y determina la ruta en función de su valor:

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}

Verifica siempre la firma del webhook antes de procesarlo. Consulta la guía de Webhooks para conocer la configuración completa, incluida la verificación de firmas y la idempotencia.

Decide si reintentar: rechazos temporales frente a definitivos

error_code te indica si vale la pena reintentar con el mismo método de pago.

Tipo de decline	Ejemplos	Acción
Soft decline	`INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`	Reintenta después de un tiempo o cuando el cliente corrija sus datos.
Hard decline	`STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`, `INVALID_ACCOUNT`	No reintentes con la misma tarjeta. Pide al cliente otro método de pago.

Consulta Transaction Failures para ver la lista completa de tipos de decline y las acciones recomendadas.

Gestión de fallos durante el checkout y durante la renovación

La forma de recuperar el pago depende de si el cliente está presente.

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

El cliente está realizando el checkout. Muestra un mensaje claro y permite que reintente o use otra tarjeta.

requires_payment_method — el cliente nunca proporcionó un método de pago. Normalmente se trata de un abandono del checkout, no de un decline. Vuelve a contactar con el cliente para que complete el pago (consulta Recuperación de carritos abandonados).
requires_customer_action — se necesita autenticación adicional (como 3DS). Haz que el cliente la complete. Consulta 3D Secure.

El cliente no está presente. Cuando falla una renovación, la suscripción pasa a on_hold y se activa subscription.on_hold. Si tu negocio tiene un periodo de gracia, primero pasa a past_due (subscription.past_due) y mantiene el acceso hasta que termina el periodo de gracia.

Los Soft declines se reintentan automáticamente si activas Subscription Payment Retries (desactivado de forma predeterminada). Los reintentos solo cubren renovaciones programadas, no cargos bajo demanda.
Los Hard declines (y los reintentos agotados) de renovaciones programadas se recuperan con Subscription Dunning, que envía un correo al cliente para que actualice su método de pago. Para fallos de cargos bajo demanda, consulta On-Demand Subscriptions.

Consulta Subscription Integration Guide para ver el flujo completo de en espera → reactivación.

Reintentar un pago fallido

Suscripciones: Activa Subscription Payment Retries para recuperar automáticamente los soft declines. Para reintentar de inmediato en lugar de esperar al momento programado, usa Manual Payment Retry desde el dashboard o la API. También puedes activar la recuperación haciendo que el cliente actualice su método de pago mediante la Update Payment Method API, que cobra cualquier importe pendiente. Pagos únicos: Reenvía el checkout o payment_link para que el cliente pueda intentarlo de nuevo con otro método. No hay reintentos automáticos para pagos únicos.

No reintentes los hard declines con la misma tarjeta. Las redes de tarjetas marcan los declines repetidos como abusivos, lo que perjudica tu tasa de autorización.

Mostrar errores a los clientes de forma segura

Muestra a los clientes un mensaje claro y amigable, nunca el error_code sin procesar ni el error_message dirigido al merchant.

En las superficies controladas por Dodo Payments (checkout, Customer Portal y correos de dunning), esta asignación ya está hecha, incluido el uso de un mensaje genérico como alternativa para los declines relacionados con fraude. Solo necesitas la asignación siguiente cuando muestres los fallos en tu propio producto.

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 reveles el motivo real de STOLEN_CARD, LOST_CARD, PICKUP_CARD o FRAUDULENT. Mostrar estos motivos puede alertar a un actor fraudulento. Muestra un mensaje de decline genérico y registra el error_code específico solo internamente.

Relacionado

Transaction Failures

Cada código de decline, su tipo y la acción recomendada.

Error Codes

Errores de la API y de la lógica de negocio que no son declines de tarjeta.

Subscription Payment Retries

Recuperación automática de soft declines en renovaciones de suscripciones.

Subscription Dunning

Secuencias de correo que recuperan hard declines.

Payment Webhooks

Esquema completo del payload de los eventos de pago.

Testing Failures

Tarjetas de prueba que simulan declines y fallos de renovación.

Integration Guides

Billing Deconstructions

Cookbooks

Cómo Dodo Payments Informa un Fallo

El webhook de `payment.failed`

Decide si reintentar: rechazos temporales frente a definitivos

Gestión de fallos durante el checkout y durante la renovación

Reintentar un pago fallido

Mostrar errores a los clientes de forma segura

Relacionado

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

​Cómo Dodo Payments Informa un Fallo

​El webhook de payment.failed

​Decide si reintentar: rechazos temporales frente a definitivos

​Gestión de fallos durante el checkout y durante la renovación

​Reintentar un pago fallido

​Mostrar errores a los clientes de forma segura

​Relacionado

Transaction Failures

Error Codes

Subscription Payment Retries

Subscription Dunning

Payment Webhooks

Testing Failures

Cómo Dodo Payments Informa un Fallo

El webhook de `payment.failed`

Decide si reintentar: rechazos temporales frente a definitivos

Gestión de fallos durante el checkout y durante la renovación

Reintentar un pago fallido

Mostrar errores a los clientes de forma segura

Relacionado