> ## 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.
# Gestionar Fallos de Pago
> Detecta pagos fallidos desde webhooks y la API, lee la razón del fallo, preséntala a los clientes de manera segura, y decide cuándo reintentar o recoger un nuevo método 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 no exitosos incluyen `cancelled`, `requires_customer_action`, y `requires_payment_method`. |
| `error_code` | string \| null | La razón estandarizada del fallo, por ejemplo `INSUFFICIENT_FUNDS` o `PROCESSING_ERROR`. Consulta la referencia de [Fallos de Transacción](/api-reference/transaction-failures) para la lista completa. |
| `error_message` | string \| null | Una explicación legible para humanos del fallo. |
| `retry_attempt` | integer | `0` para el cargo original. `1` o superior identifica un reintento de renovación de suscripción programada. |
`error_code` e `error_message` son `null` hasta que un pago realmente falle. Siempre verifica `status` primero, luego lee los campos de error.
## El Webhook `payment.failed`
La manera más confiable de detectar un fallo es el webhook `payment.failed`. El evento envuelve el objeto de pago completo en `data`:
```json payment.failed payload expandable theme={null}
{
"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 manejador mínimo lee `error_code` y lo encamina:
```javascript Node.js expandable theme={null}
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 });
});
```
```python Python expandable theme={null}
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}
```
Siempre verifica la firma del webhook antes de procesar. Consulta la [guía de Webhooks](/developer-resources/webhooks) para la configuración completa, incluyendo la verificación de firma e idempotencia.
## Decidir si Reintentar: Rechazos Suaves vs. Duros
El `error_code` te indica si vale la pena reintentar el mismo método de pago.
| Tipo de Rechazo | Qué significa | Qué hacer |
| ----------------- | ----------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| **Rechazo suave** | Temporal o corregible (por ejemplo `INSUFFICIENT_FUNDS`, `PROCESSING_ERROR`, `NETWORK_ERROR`, `TRY_AGAIN_LATER`). | Reintentar — después de un retraso, o una vez que el cliente corrija su entrada — puede tener éxito. |
| **Rechazo duro** | Terminal (por ejemplo `STOLEN_CARD`, `LOST_CARD`, `DO_NOT_HONOR`, `FRAUDULENT`). | **No** reintentar con la misma tarjeta. Solicita al cliente un método de pago diferente. |
La referencia de [Fallos de Transacción](/api-reference/transaction-failures) lista el tipo de rechazo y la acción recomendada para cada `error_code`.
## Manejo de Fallos en el Pago vs. en la Renovación
Cómo te recuperas depende de si el cliente está presente.
El cliente está realizando la compra activamente. Muestra un mensaje claro y permite que reintenten inmediatamente o usen otra tarjeta.
* `requires_payment_method` — el cliente nunca proporcionó un método de pago: no ingresaron detalles de la tarjeta o se les solicitó uno y no tomaron acción. Esto usualmente es un **abandono** de carrito de compra, no un rechazo — vuelve a involucrar al cliente para completar el pago (consulta [Recuperación de Carrito Abandonado](/features/recovery/abandoned-cart-recovery)).
* `requires_customer_action` — se necesita autenticación adicional (como 3DS); haz que el cliente la complete. Consulta el manejo de [3D Secure](/features/payment-methods/cards#3d-secure-authentication).
El cliente no está presente, por lo que no puedes solicitarle en tiempo real. Cuando una renovación falla, la suscripción se mueve a `on_hold` y se dispara `subscription.on_hold`.
* **Rechazos suaves** se reintentan automáticamente por [Reintentos de Pago de Suscripción](/features/recovery/payment-retries).
* **Rechazos duros** (y reintentos agotados) se recuperan mejor con [Gestión de Suscripción](/features/recovery/subscription-dunning), que envía correos electrónicos al cliente para actualizar su método de pago.
Consulta la [Guía de Integración de Suscripciones](/developer-resources/subscription-integration-guide#handling-subscription-on-hold) para el flujo completo de en espera → reactivar.
## Reintentando un Pago Fallido
* **Suscripciones:** Activa [Reintentos de Pago de Suscripción](/features/recovery/payment-retries) para recuperar rechazos suaves sin trabajo de integración. También puedes desencadenar la recuperación haciendo que el cliente actualice su método de pago a través de la [API de Actualización de Método de Pago](/api-reference/subscriptions/update-payment-method), que carga cualquier saldo pendiente.
* **Pagos únicos:** Reenvía el checkout o `payment_link` para que el cliente pueda intentarlo de nuevo con un método diferente. No hay reintento automático para pagos únicos.
No reintentes rechazos duros con la misma tarjeta. Las redes de tarjetas pueden marcar rechazos repetidos como abusivos, lo que perjudica tu tasa de autorización.
## Mostrar Errores a los Clientes de Manera Segura
Muestra a los clientes un mensaje amigable — nunca el `error_code` crudo.
```javascript Customer-facing messaging expandable theme={null}
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 la razón real para `STOLEN_CARD`, `LOST_CARD`, `PICKUP_CARD`, o `FRAUDULENT`.** Mostrar estos puede alertar a un actor fraudulento. Muestra un mensaje genérico de rechazo y solo registra el `error_code` específico internamente.
## Relacionado
Cada código de rechazo, su tipo, y la acción recomendada.
Errores de API y lógica de negocio que no son rechazos de tarjeta.
Recuperación automática de rechazos suaves en renovaciones de suscripción.
Secuencias de email que recuperan rechazos duros.
Esquema completo de carga útil para eventos de pago.
Tarjetas de prueba que simulan rechazos y fallos de renovación.