Gestionar Fallos de Pago

Cuando un pago falla, Dodo Payments te indica por qué a través de un error_code estandarizado y un error_message legible para humanos. Esta guía muestra cómo leer esos campos, decidir si vale la pena reintentar, y recuperar el pago sin exponer información sensible a los clientes.

Cómo Dodo Payments Informa un Fallo

Cada pago fallido, ya sea una compra única o una renovación de suscripción, lleva los mismos campos de fallo en el objeto de pago:

Campo	Tipo	Descripción
`status`	string	`failed` para un pago fallido. Otros estados que no indican éxito incluyen `cancelled`, `requires_customer_action` y `requires_payment_method`.
`error_code`	string \| null	El motivo estandarizado del fallo, por ejemplo `INSUFFICIENT_FUNDS` o `PROCESSING_ERROR`. Consulta la referencia de Transaction Failures para ver la lista completa.
`error_message`	string \| null	Una explicación del fallo en lenguaje natural, escrita para ti y no para tu cliente. Para un `error_code` estandarizado, se trata de un encabezado más la acción recomendada, no del texto sin procesar del procesador.
`retry_attempt`	integer	`0` del cargo original. `1` o superior identifica un reintento programado de renovación de una suscripción.

error_code e error_message son null hasta que un pago realmente falle. Siempre verifica status primero, luego lee los campos de error.

error_message de la API del comercio es texto dirigido al comercio. Puede indicar el motivo real de un rechazo, incluidos los relacionados con fraude, por lo que nunca debes mostrarlo directamente al cliente. En su lugar, asigna error_code a tu propio texto seguro para el cliente, como se muestra en Mostrar errores a los clientes de forma segura.

El webhook de `payment.failed`

La forma más fiable de detectar un fallo es el webhook de payment.failed. 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 decide según 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 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}

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 rechazo	Qué significa	Qué hacer
Rechazo temporal	Temporal o corregible (por ejemplo, `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`).	Reintentar — después de un tiempo o una vez que el cliente corrija los datos introducidos — puede funcionar.
Rechazo definitivo	Terminal (por ejemplo, `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`).	No reintentes con la misma tarjeta. Pide al cliente un método de pago diferente.

La referencia de Transaction Failures indica el tipo de rechazo y la acción recomendada para cada error_code.

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á completando el checkout activamente. Muestra un mensaje claro y permítele reintentar de inmediato o usar otra tarjeta.

requires_payment_method — el cliente nunca proporcionó un método de pago: no introdujo los datos de la tarjeta o se le pidió que lo hiciera y no realizó ninguna acción. Por lo general, esto es un abandono del checkout, no un rechazo: vuelve a captar la atención del 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 Gestión de 3D Secure.

El cliente no está presente, por lo que no puedes solicitarle nada en tiempo real. Cuando falla una renovación, la suscripción pasa a on_hold y se activa subscription.on_hold.

Los rechazos temporales se vuelven a intentar automáticamente mediante Reintentos de pagos de suscripciones.
Los rechazos definitivos (y los reintentos agotados) se recuperan mejor con Gestión de cobros de suscripciones, que envía un correo al cliente para que actualice su método de pago.

Consulta la Guía de integración de suscripciones para conocer el flujo completo de en espera → reactivación.

Reintentar un pago fallido

Suscripciones: activa Reintentos de pagos de suscripciones para recuperar rechazos temporales sin trabajo de integración. También puedes activar la recuperación haciendo que el cliente actualice su método de pago mediante la API de actualización del método de pago, que cobra cualquier importe pendiente.
Pagos únicos: vuelve a enviar el checkout o payment_link para que el cliente pueda intentarlo de nuevo con un método diferente. No existe un reintento automático para los pagos únicos.

No reintentes rechazos definitivos con la misma tarjeta. Las redes de tarjetas pueden marcar los rechazos repetidos como abusivos, lo que perjudica tu tasa de autorización.

Mostrar errores a los clientes de forma segura

Muestra al cliente un mensaje cordial: nunca el error_code sin procesar y nunca el error_message dirigido al comercio.

En las superficies que controla Dodo Payments — el checkout, el Customer Portal y los correos de gestión de cobros — esta asignación ya está hecha, incluido el uso de un mensaje genérico como alternativa para los rechazos relacionados con fraude. Solo necesitas la asignación siguiente cuando muestres 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 ni FRAUDULENT. Mostrar estos motivos puede alertar a un actor fraudulento. Muestra un mensaje de rechazo genérico y registra internamente únicamente el error_code específico.

Relacionado

Transaction Failures

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

Error Codes

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

Subscription Payment Retries

Recuperación automática de rechazos temporales durante las renovaciones de suscripciones.

Subscription Dunning

Secuencias de correos que recuperan rechazos definitivos.

Payment Webhooks

Esquema completo de la carga útil para eventos de pago.

Testing Failures

Tarjetas de prueba que simulan rechazos 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