Descripción general
Las suscripciones bajo demanda te permiten autorizar el método de pago de un cliente una vez y luego cobrar montos variables cuando lo necesites, en lugar de en un horario fijo. Esta función está disponible para todas las cuentas; no se requiere aprobación. Utiliza esta guía para:- Crear una suscripción bajo demanda (autorizar un mandato con un precio inicial opcional)
- Activar cargos posteriores con montos personalizados
- Rastrear resultados utilizando webhooks
Requisitos previos
- Cuenta de comerciante de Dodo Payments y clave API
- Secreto de webhook configurado y un endpoint para recibir eventos
- Un producto de suscripción en tu catálogo
Cómo funciona bajo demanda
- Creas una suscripción con el objeto
on_demandpara autorizar un método de pago y, opcionalmente, cobrar un cargo inicial. - Más adelante, creas cargos contra esa suscripción con importes personalizados usando el endpoint dedicado de cargos.
- Escuchas webhooks (p. ej.,
payment.succeeded,payment.failed) para actualizar tu sistema.
Crear una suscripción bajo demanda
Endpoint: POST /checkouts Campos clave de la solicitud (cuerpo):Consúltalos en Crear Sesión de Pago
Crear una suscripción bajo demanda
- Node.js SDK
- Python SDK
- Go SDK
- cURL
Success
Cargar una suscripción bajo demanda
Después de que se autorice el mandato, crea cargos según sea necesario. Endpoint: POST /subscriptions/{subscription_id}/charge Campos clave de la solicitud (cuerpo):Charge request body parameters
Charge request body parameters
integer
requerido
Importe a cobrar (en la unidad monetaria más pequeña). Ejemplo: para cobrar $25.00, pasa
2500.string
Anulación opcional de moneda para el cargo.
string
Anulación opcional de descripción para este cargo.
boolean
Si es verdadero, incluye tarifas de moneda adaptativa dentro de
product_price. Si es falso, las tarifas se agregan encima.object
Especifica cómo se utiliza el saldo de la billetera del cliente para liquidar este cargo.
object
Metadatos adicionales para el pago. Si se omiten, se utilizan los metadatos de la suscripción.
- Node.js SDK
- Python SDK
- Go SDK
- cURL
Success
Gestión de cargos fallidos
Cuando falla un cargo contra una suscripción bajo demanda, tú decides qué sucede después. A diferencia de las suscripciones programadas —donde una renovación fallida detiene la facturación automática posterior—, las suscripciones bajo demanda siguen pudiendo cobrarse después de un fallo. Puedes volver a llamar al endpoint de cargos como parte de tu propia lógica de reintentos.Qué sucede cuando falla
1
Charge attempt fails
La solicitud
POST /subscriptions/{subscription_id}/charge devuelve una respuesta de error o se completa de forma asíncrona y emite un webhook payment.failed con el motivo del rechazo.2
Subscription may transition to on_hold
La suscripción puede pasar al estado
on_hold y emitir un webhook subscription.on_hold (consulta Estados de la suscripción → En espera). Esto es una señal, no un bloqueo. En las suscripciones bajo demanda, on_hold no impide que vuelvas a cobrar.3
Retry the charge (your call)
En los flujos bajo demanda, Dodo no reintenta automáticamente. Puedes volver a llamar a
POST /subscriptions/{subscription_id}/charge en cualquier momento para reintentar. Aplica la política de reintentos seguros que aparece a continuación —usa un retroceso exponencial, omite los rechazos definitivos y evita los patrones de ráfaga— para que nuestros sistemas de fraude y riesgo no marquen los reintentos.4
Optionally, ask the customer for a new payment method
Si los reintentos siguen fallando porque el método de pago está dañado (tarjeta vencida, cuenta cerrada, etc.), utiliza
POST /subscriptions/{subscription_id}/update-payment-method para recopilar uno nuevo del cliente. Tras completarse correctamente, la suscripción vuelve a active y se emiten los webhooks payment.succeeded seguidos de subscription.active.Bajo demanda frente a programadas: Para las suscripciones programadas, Dodo ejecuta sus propios reintentos de renovación y gestión de morosidad. Para las suscripciones bajo demanda, tú administras la política de reintentos porque solo tú sabes cuándo debe producirse el siguiente cargo (depende de tus eventos de uso, no de un calendario).
Secuencia de webhooks tras un cargo bajo demanda fallido
Los eventos 3 y 4 solo se activan después de que un cargo posterior se complete correctamente.
Responsabilidad de los reintentos
Gestión de morosidad de suscripciones —la secuencia integrada de recuperación por correo electrónico— se limita a pagos de renovación fallidos en suscripciones programadas y a cancelaciones iniciadas por el cliente. No está diseñada para fallos de cargos bajo demanda. Comunícate directamente con el cliente (por ejemplo, mediante un correo transaccional o un aviso en la aplicación) cuando decidas que es necesario actualizar el método de pago.Reintentos de pago
Nuestro sistema de detección de fraude puede bloquear patrones de reintentos agresivos (y marcarlos como posibles pruebas de tarjetas). Sigue una política de reintentos seguros.Principios para políticas de reintentos seguros
- Mecanismo de retroceso: Utiliza un retroceso exponencial entre reintentos.
- Límites de reintentos: Limita el total de reintentos (3–4 intentos como máximo).
- Filtrado inteligente: Reintenta solo los fallos que admiten reintento (por ejemplo, errores de red o del emisor, fondos insuficientes); nunca reintentes rechazos definitivos.
- Prevención de pruebas de tarjetas: No reintentes fallos como
DO_NOT_HONOR,STOLEN_CARD,LOST_CARD,PICKUP_CARD,FRAUDULENT,AUTHENTICATION_FAILURE. - Variar los metadatos (opcional): Si mantienes tu propio sistema de reintentos, diferencia los reintentos mediante metadatos (por ejemplo,
retry_attempt).
Calendario de reintentos sugerido (suscripciones)
- 1.er intento: Inmediatamente al crear el cargo
- 2.º intento: Después de 3 días
- 3.er intento: Después de 7 días más (10 días en total)
- 4.º intento (final): Después de otros 7 días (17 días en total)
Evita los reintentos en ráfaga; alinéate con la hora de autorización
- Basa los reintentos en la marca de tiempo de la autorización original para evitar un comportamiento de «ráfaga» en tu cartera.
- Ejemplo: Si el cliente inicia una prueba o un mandato hoy a la 1:10 p. m., programa los reintentos posteriores a la 1:10 p. m. de los días siguientes según tu retroceso (por ejemplo, +3 días → 1:10 p. m., +7 días → 1:10 p. m.).
- Como alternativa, si almacenas la hora del último pago correcto
T, programa el siguiente intento enT + X dayspara conservar la alineación horaria.
Zona horaria y horario de verano (DST): utiliza un estándar horario coherente para la programación y conviértelo únicamente para mostrarlo, a fin de mantener los intervalos.
Códigos de rechazo que no debes reintentar
STOLEN_CARDDO_NOT_HONORFRAUDULENTPICKUP_CARDAUTHENTICATION_FAILURELOST_CARD
Para consultar una lista completa de los motivos de rechazo y saber si el usuario puede corregirlos, consulta la documentación de
Fallos de transacciones.
Directrices de implementación (sin código)
- Utiliza un programador o una cola que conserve marcas de tiempo precisas; calcula el siguiente intento exactamente en el desplazamiento horario correspondiente (por ejemplo,
T + 3 daysa la misma hora HH:MM). - Mantén y consulta la marca de tiempo del último pago correcto
Tpara calcular el siguiente intento; no agrupes varias suscripciones en el mismo instante. - Evalúa siempre el último motivo de rechazo; detén los reintentos para los rechazos definitivos de la lista anterior.
- Limita los reintentos simultáneos por cliente y por cuenta para evitar aumentos repentinos accidentales.
- Comunícate de forma proactiva: envía un correo electrónico o SMS al cliente para que actualice su método de pago antes del siguiente intento programado.
- Utiliza los metadatos únicamente para observabilidad (por ejemplo,
retry_attempt); nunca intentes «evadir» los sistemas de fraude o riesgo rotando campos irrelevantes.
Cancelación
Las suscripciones bajo demanda siguen un flujo de cancelación distinto al de las suscripciones programadas porque no existe un ciclo de facturación fijo que sirva de referencia para una fecha de finalización inmediata.Comportamiento del Customer Portal
Cuando un cliente cancela una suscripción bajo demanda desde el Customer Portal, la cancelación se programa para la siguiente fecha de facturación de forma predeterminada. La opción Cancelar ahora no se muestra intencionadamente para las suscripciones bajo demanda. El motivo es que las suscripciones bajo demanda no tienen fechas de renovación recurrentes predecibles: la hora del siguiente cargo depende completamente de tus eventos de uso. Programar la cancelación para la siguiente fecha de facturación mantiene activo el mandato hasta el límite del periodo, de modo que cualquier uso en curso aún pueda cobrarse; después, finaliza la suscripción correctamente. Después de que el cliente confirme la cancelación:- La suscripción permanece en
activey se puede seguir cobrando mediantePOST /subscriptions/{id}/chargehasta la fecha de cancelación programada. cancel_at_next_billing_datese establece entrueen la suscripción.- Se emite un webhook
subscription.cancelledcuando la cancelación entra en vigor.
Si necesitas finalizar la suscripción de inmediato (por ejemplo, en respuesta a un reembolso o una solicitud de asistencia), cancélala mediante la API de forma programática en lugar de depender del flujo del portal del cliente.
Cancelar mediante programación
Puedes cancelar una suscripción bajo demanda mediante la API en cualquier momento. Tú decides si la cancelación es inmediata o programada. Endpoint: PATCH /subscriptions/{subscription_id}- Cancel immediately
- Cancel at next billing date
Establece
status de la suscripción en cancelled para finalizarla de inmediato. El mandato se revoca y no se pueden crear más cargos.cURL
Webhooks durante la cancelación
Seguimiento de resultados con webhooks
Implementa la gestión de webhooks para seguir el recorrido del cliente. Consulta Implementación de webhooks.- subscription.active: Mandato autorizado y suscripción activada
- subscription.failed: Error en la creación (por ejemplo, fallo del mandato)
- subscription.on_hold: Suscripción puesta en espera (por ejemplo, estado impago)
- subscription.cancelled: Suscripción cancelada por completo (consulta Cancelación)
- payment.succeeded: Cargo completado correctamente
- payment.failed: Cargo fallido
Pruebas y próximos pasos
1
Create in test mode
Utiliza tu clave de API de prueba para crear la suscripción; después, abre el
checkout_url devuelto y completa el mandato.2
Trigger a charge
Llama al endpoint de cargos con un
product_price pequeño (por ejemplo, 100) y comprueba que recibes payment.succeeded.3
Go live
Cambia a tu clave de API activa una vez que hayas validado los eventos y las actualizaciones del estado interno.
Solución de problemas
- 422 Invalid Request: Asegúrate de proporcionar
on_demand.mandate_onlyal crear la suscripción yproduct_pricepara los cargos. - Errores de moneda: Si anulas
product_currency, confirma que sea compatible con tu cuenta y tu cliente. - No se recibieron webhooks: Verifica la configuración de la URL del webhook y del secreto de firma.