> ## 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.
# Reintento manual de pagos
> Reintenta manualmente el pago fallido de renovación de una suscripción desde el dashboard o la API, sin esperar al siguiente reintento automático.
Manual Retry vuelve a intentar el pago de **renovación** fallido de una suscripción en el momento en que lo solicitas, desde la página de detalles del pago o mediante la API. Cobra el método de pago guardado en la suscripción y funciona independientemente del calendario de [Payment Retries](/features/recovery/payment-retries) automáticos.
## ¿Qué es Manual Retry?
Cuando falla un pago de renovación, la suscripción pasa a `on_hold` y [Payment Retries](/features/recovery/payment-retries) vuelve a intentar el cobro según un calendario con intervalos crecientes. A veces sabes que el pago se realizará ahora: el cliente ha confirmado que recargó su cuenta o tu equipo de soporte está hablando con él. Manual Retry te permite enviar un intento inmediatamente en lugar de esperar horas o días al siguiente intento programado.
* **Solo pagos de renovación**: Manual Retry se aplica a las facturas de renovación de suscripciones mientras la suscripción está en `on_hold`. Los primeros pagos, los pagos únicos, los cargos por cambio de plan y los cargos bajo demanda no son aptos.
* **Sin acción del cliente**: el cargo se realiza en el método de pago ya guardado en la suscripción.
* **Independiente de los reintentos automáticos**: un reintento manual no consume un intento del calendario automático, no cambia el siguiente reintento programado y funciona incluso cuando Payment Retries está desactivado.
* **Reintenta la factura, no el pago**: un pago fallido es solo el punto de partida. Dodo Payments busca la factura de renovación abierta asociada y cobra esa deuda, por lo que no importa desde qué pago fallido de la factura realices el reintento.
## Reintentar desde el dashboard
Ve a **Transactions → Payments** y haz clic en el pago de renovación fallido para abrir su página de **Transaction details**.
Haz clic en **Retry Payment Manually** en la esquina superior derecha. El botón solo está disponible mientras el pago sea [eligible](#eligibility).
Se crea un nuevo pago para el intento y aparece en el **Activity Log**. Si el cargo se realiza correctamente, la suscripción vuelve a `active` y la siguiente fecha de facturación avanza con normalidad. Si el procesador de pagos aún no ha liquidado el cargo, el pago aparece como en curso hasta que el webhook `payment.succeeded` o `payment.failed` informe del resultado.
## Elegibilidad
El reintento manual solo se envía cuando se cumplen todas las comprobaciones siguientes. La columna **Reason code** es lo que devuelve la API: en `reason` en `GET /payments/{payment_id}/retry` y como el error `code` en `POST /payments/{payment_id}/retry`.
| Comprobación | Requisito | Código de motivo |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- |
| Tipo de pago | Un pago de **renovación** de suscripción cuya factura siga abierta. Los pagos sin factura, los primeros pagos, los pagos únicos, los cargos por cambio de plan y los cargos bajo demanda no se pueden reintentar. | `PAYMENT_NOT_RETRYABLE` |
| Estado de la suscripción | `on_hold` | `SUBSCRIPTION_INACTIVE` |
| Cancelación programada | La suscripción no está programada para cancelarse en la próxima fecha de facturación. | `CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION` |
| Método de pago guardado | La suscripción tiene un método de pago guardado que se puede cobrar. | `SUBSCRIPTION_HAS_NO_PAYMENT_METHOD` |
| Último fallo | El fallo más reciente es un **rechazo temporal**. Un rechazo permanente o un fallo sin código de error clasificado no se puede reintentar. | `MANUAL_RETRY_HARD_DECLINE` |
| Nada en curso | Ningún pago de la factura está `processing` ni carece todavía de un estado registrado. Se trata de un intento, manual o automático, que acaba de enviarse y aún no ha informado del resultado. Espera primero a conocer su resultado. | `MANUAL_RETRY_IN_FLIGHT` |
| El pago más reciente falló | El pago más reciente de la factura tiene el estado `failed`. Un pago más reciente en cualquier otro estado que no sea `failed`, como `requires_customer_action`, `requires_payment_method` o `cancelled`, bloquea el reintento incluso cuando no hay nada en curso. | `PREVIOUS_PAYMENT_PENDING` |
| No se ha pagado todavía | Ningún pago de la factura se ha realizado correctamente. | `MANUAL_RETRY_ALREADY_PAID` |
| Límite de reintentos | Se han enviado menos de 3 reintentos manuales en la factura y ha pasado el periodo de espera. Consulta [Retry Limits](#retry-limits). | `MANUAL_RETRY_LIMIT_REACHED` |
| Cliente | El cliente no está en tu [blocklist](/features/customer-blocklist). | `PAYMENT_NOT_RETRYABLE` |
| Conector de pagos | Para las suscripciones [BYOP](/features/byop), el conector está habilitado. | `BYOP_CONNECTOR_DISABLED` |
| Modo live | En live mode, tu empresa tiene habilitados los pagos live. | `MERCHANT_NOT_LIVE` |
Manual Retry es más restrictivo que los reintentos automáticos en un aspecto: requiere que la suscripción esté en `on_hold`. Los reintentos automáticos siguen ejecutándose para otros estados que no sean activos; consulta [Subscription Status Transitions](/features/recovery/payment-retries#subscription-status-transitions).
Reintentar un rechazo permanente contra la misma tarjeta no puede tener éxito y los rechazos repetidos perjudican tu tasa de autorización. Cuando el motivo sea `MANUAL_RETRY_HARD_DECLINE`, pide al cliente que actualice su método de pago. [Subscription Dunning](/features/recovery/subscription-dunning) lo hace automáticamente.
## Límites de reintentos
Cada factura de renovación permite **3** reintentos manuales, con un periodo de espera entre ellos:
| Reintento manual | Disponible |
| ---------------- | --------------------------- |
| 1 | En cuanto el pago sea apto |
| 2 | 1 hora después del primero |
| 3 | 3 horas después del segundo |
Los límites se aplican tanto en test mode como en live mode. Cuando se rechaza un reintento por este motivo, la API devuelve `MANUAL_RETRY_LIMIT_REACHED` (HTTP `429`). El cuerpo del error solo contiene `code` y `message`. Para saber cuándo se habilita el siguiente reintento, [consulta el estado del reintento](#check-whether-a-payment-can-be-retried) y lee `retry_available_at`. Es `null` una vez consumidos los tres.
Los reintentos automáticos no cuentan para este límite y los reintentos manuales no cuentan para los 8 intentos del calendario automático.
## Reintentos manuales frente a automáticos
| | Manual Retry | Payment Retries |
| --------------------------------------- | ---------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| **Activador** | Tú, desde el dashboard o la API | Dodo Payments, según un calendario con intervalos crecientes |
| **Momento** | Inmediatamente | 12 horas después del fallo y, posteriormente, con intervalos cada vez mayores |
| **Intentos** | 3 por factura, con una espera de 1 hora y después de 3 horas | Hasta 8 por factura, dentro de tu ventana de recuperación |
| **Requiere Payment Retries habilitado** | No | Sí |
| **Efecto sobre el otro** | Ninguno. Un fallo manual no programa ni mueve un intento automático. | Ninguno. La cadena automática continúa independientemente de los envíos manuales. |
| **Analytics** | Se contabiliza en las métricas de **Payment retries** de la pestaña Recovery | Se contabiliza en las mismas métricas |
## Reintentar mediante la API
Comprueba primero la elegibilidad y después envía el reintento. Ambos endpoints reciben el ID de un pago fallido.
### Comprobar si se puede reintentar un pago
`GET /payments/{payment_id}/retry` nunca falla cuando el pago no es apto. En su lugar, devuelve `can_retry: false` con el código `reason`, para que tu dashboard o tus herramientas de soporte puedan mostrar el mismo estado que muestra el dashboard de Dodo Payments. Requiere el rol **Viewer**.
```typescript Node.js theme={null}
import DodoPayments from 'dodopayments';
const client = new DodoPayments({
bearerToken: process.env.DODO_PAYMENTS_API_KEY,
});
const state = await client.payments.retrieveRetryState('pay_0NmDtkE0iRvmeTcT6t0ol');
if (state.can_retry) {
console.log(`Retry available. ${state.sends_used}/${state.sends_allowed} used.`);
} else {
console.log(`Cannot retry: ${state.reason}. Next window: ${state.retry_available_at}`);
}
```
```python Python theme={null}
import os
from dodopayments import DodoPayments
client = DodoPayments(bearer_token=os.environ["DODO_PAYMENTS_API_KEY"])
state = client.payments.retrieve_retry_state("pay_0NmDtkE0iRvmeTcT6t0ol")
if state.can_retry:
print(f"Retry available. {state.sends_used}/{state.sends_allowed} used.")
else:
print(f"Cannot retry: {state.reason}. Next window: {state.retry_available_at}")
```
```bash cURL theme={null}
curl https://live.dodopayments.com/payments/pay_0NmDtkE0iRvmeTcT6t0ol/retry \
-H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"
```
```json Response theme={null}
{
"can_retry": false,
"reason": "MANUAL_RETRY_LIMIT_REACHED",
"sends_used": 1,
"sends_allowed": 3,
"retry_available_at": "2026-08-26T16:51:00Z"
}
```
| Campo | Descripción |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `can_retry` | `true` cuando el reintento se enviaría ahora mismo. |
| `reason` | El código con el que fallaría el reintento. `null` cuando `can_retry` sea `true`. |
| `sends_used` | Reintentos manuales ya enviados para esta factura. |
| `sends_allowed` | Siempre `3`. |
| `retry_available_at` | Cuándo se habilita el siguiente reintento manual. `null` cuando no queda ningún reintento o cuando el rechazo no está relacionado con el periodo de espera. |
### Enviar un reintento manual
`POST /payments/{payment_id}/retry` crea un nuevo pago y cobra el método de pago guardado. Requiere el rol **Editor**.
```typescript Node.js theme={null}
const retry = await client.payments.retry('pay_0NmDtkE0iRvmeTcT6t0ol');
console.log(retry.payment_id, retry.status);
```
```python Python theme={null}
retry = client.payments.retry("pay_0NmDtkE0iRvmeTcT6t0ol")
print(retry.payment_id, retry.status)
```
```bash cURL theme={null}
curl -X POST https://live.dodopayments.com/payments/pay_0NmDtkE0iRvmeTcT6t0ol/retry \
-H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"
```
```json Response theme={null}
{
"payment_id": "pay_2IjeQm4hqU6RA4Z4kwDee",
"invoice_id": "inv_9Kp2mQ7vRt4LxYw3",
"status": "processing",
"retry_attempt": 1,
"is_manual_retry": true,
"sends_used": 1,
"sends_allowed": 3,
"retry_available_at": "2026-08-26T16:51:00Z"
}
```
| Campo | Descripción |
| --------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payment_id` | El nuevo pago creado para este intento. |
| `invoice_id` | La factura de renovación cobrada. |
| `status` | Resultado del cargo. `processing` significa que el procesador aún no lo ha liquidado. `null` significa que no se registró ningún resultado antes de devolver la respuesta. En ambos casos, los webhooks del pago informan del resultado final. |
| `retry_attempt` | Posición de este intento entre los reintentos manuales de la factura, empezando por `1`. |
| `is_manual_retry` | Siempre `true` en este endpoint. |
| `sends_used`, `sends_allowed`, `retry_available_at` | Estado del límite de reintentos después de este envío. `retry_available_at` solo corresponde al reloj del periodo de espera. Se establece incluso si este cargo se realiza correctamente; en ese caso, la factura está pagada y no se habilita ningún otro reintento. |
### Respuestas de error
| Estado HTTP | Códigos | Qué hacer |
| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `404` | `NOT_FOUND` | El pago no pertenece a tu empresa. |
| `409` | `MANUAL_RETRY_IN_FLIGHT`, `PREVIOUS_PAYMENT_PENDING`, `CHARGE_NOT_ALLOWED_FOR_SCHEDULED_CANCELLATION` | Es temporal o primero debe cambiar alguna otra condición. Espera a que el pago en curso o pendiente alcance un estado final, o elimina la cancelación programada. |
| `422` | `PAYMENT_NOT_RETRYABLE`, `SUBSCRIPTION_INACTIVE`, `SUBSCRIPTION_HAS_NO_PAYMENT_METHOD`, `MANUAL_RETRY_HARD_DECLINE`, `MANUAL_RETRY_ALREADY_PAID`, `BYOP_CONNECTOR_DISABLED`, `MERCHANT_NOT_LIVE` | Este pago no se puede reintentar. No repitas la llamada. |
| `429` | `MANUAL_RETRY_LIMIT_REACHED` | [Consulta el estado del reintento](#check-whether-a-payment-can-be-retried) y espera hasta `retry_available_at`, o detente cuando se hayan consumido los tres reintentos. |
Todos los códigos se describen en la referencia de [Error Codes](/api-reference/error-codes).
## Webhooks
Un reintento manual crea un pago normal, por lo que se activan los mismos webhooks que para cualquier intento de renovación:
| Evento | Se activa cuando |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `payment.succeeded` | Se ha cobrado el reintento. `subscription.active` le sigue cuando se reactiva la suscripción. |
| `payment.failed` | Se rechaza el reintento. La suscripción permanece en `on_hold` y no se programa ningún reintento automático a partir de un fallo manual. |
| `payment.processing` | El procesador ha aceptado el cargo, pero todavía no lo ha liquidado. |
En el objeto de pago de estos eventos, `retry_attempt` es `1` o superior y `subscription_id` está establecido, exactamente igual que en un reintento automático. Conserva `payment_id` de la respuesta del reintento si necesitas distinguir un intento manual de uno programado.
Esquemas completos de carga útil para eventos de pago.
## Relacionado
El calendario automático de intervalos crecientes que funciona junto con los reintentos manuales.
Envía un correo al cliente para que actualice su método de pago después de un rechazo permanente.
Lee los códigos de rechazo y decide cuándo vale la pena reintentar.
Cada código `MANUAL_RETRY_*`, su activador y su mensaje.