Reintento manual de pagos

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 automáticos.

¿Qué es Manual Retry?

Cuando falla un pago de renovación, la suscripción pasa a on_hold y 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

Open the failed payment

Ve a Transactions → Payments y haz clic en el pago de renovación fallido para abrir su página de Transaction details.

Click Retry Payment Manually

Haz clic en Retry Payment Manually en la esquina superior derecha. El botón solo está disponible mientras el pago sea eligible.

Check the result

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.

Página de detalles de la transacción de un pago fallido que muestra el código y el mensaje de error, un Activity Log y un botón Retry Payment Manually — Retry Payment Manually on the transaction details page of a failed renewal

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.	`MANUAL_RETRY_LIMIT_REACHED`
Cliente	El cliente no está en tu blocklist.	`PAYMENT_NOT_RETRYABLE`
Conector de pagos	Para las suscripciones 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.

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 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 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.

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}`);
}

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}")

curl https://live.dodopayments.com/payments/pay_0NmDtkE0iRvmeTcT6t0ol/retry \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"

Response

{
  "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.

const retry = await client.payments.retry('pay_0NmDtkE0iRvmeTcT6t0ol');

console.log(retry.payment_id, retry.status);

retry = client.payments.retry("pay_0NmDtkE0iRvmeTcT6t0ol")

print(retry.payment_id, retry.status)

curl -X POST https://live.dodopayments.com/payments/pay_0NmDtkE0iRvmeTcT6t0ol/retry \
  -H "Authorization: Bearer $DODO_PAYMENTS_API_KEY"

Response

{
  "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 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.

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.

Payment Webhook Payloads

Esquemas completos de carga útil para eventos de pago.

Relacionado

Subscription Payment Retries

El calendario automático de intervalos crecientes que funciona junto con los reintentos manuales.

Subscription Dunning

Envía un correo al cliente para que actualice su método de pago después de un rechazo permanente.

Handle Payment Failures

Lee los códigos de rechazo y decide cuándo vale la pena reintentar.

Error Codes

Cada código MANUAL_RETRY_*, su activador y su mensaje.

Getting Started

Features

Integrate

Merchant of Record

Miscellaneous

¿Qué es Manual Retry?

Reintentar desde el dashboard

Elegibilidad

Límites de reintentos

Reintentos manuales frente a automáticos

Reintentar mediante la API

Comprobar si se puede reintentar un pago

Enviar un reintento manual

Respuestas de error

Webhooks

Payment Webhook Payloads

Relacionado

Subscription Payment Retries

Subscription Dunning

Handle Payment Failures

Error Codes

​¿Qué es Manual Retry?

​Reintentar desde el dashboard

​Elegibilidad

​Límites de reintentos

​Reintentos manuales frente a automáticos

​Reintentar mediante la API

​Comprobar si se puede reintentar un pago

​Enviar un reintento manual

​Respuestas de error

​Webhooks

Payment Webhook Payloads

​Relacionado

Subscription Payment Retries

Subscription Dunning

Handle Payment Failures

Error Codes

¿Qué es Manual Retry?

Reintentar desde el dashboard

Elegibilidad

Límites de reintentos

Reintentos manuales frente a automáticos

Reintentar mediante la API

Comprobar si se puede reintentar un pago

Enviar un reintento manual

Respuestas de error

Webhooks

Relacionado