Descripción general de las suscripciones
Las suscripciones te permiten cobrar a un cliente de forma recurrente. MONEI gestiona el ciclo de facturación automáticamente — crea y activa una suscripción, y MONEI cobra al cliente en cada intervalo de facturación.
Ciclo de vida de una suscripción
Una suscripción pasa por varios estados a lo largo de su vida:
Estados
| Estado | Descripción |
|---|---|
| PENDING | Suscripción creada, pendiente de activación. El cliente aún no ha proporcionado un método de pago. |
| TRIALING | Periodo de prueba activo. Se realizó un pago de verificación de €0 para validar el método de pago. La facturación comienza al finalizar el periodo de prueba. |
| ACTIVE | Los pagos recurrentes se cobran en cada intervalo de facturación. |
| PAUSED | La facturación está suspendida temporalmente. La suscripción puede reanudarse en cualquier momento. |
| PAST_DUE | Un pago recurrente ha fallado. MONEI reintentará según el calendario de reintentos. |
| CANCELED | La suscripción ha sido cancelada permanentemente. No se realizarán más cobros. |
| EXPIRED | La suscripción no se activó a tiempo y ya no puede utilizarse. |
Intervalos de facturación
Configura la frecuencia con la que se cobra al cliente usando interval e intervalCount:
| interval | intervalCount | Frecuencia de facturación |
|---|---|---|
| day | 1 | Cada día |
| week | 1 | Cada semana |
| week | 2 | Cada 2 semanas |
| month | 1 | Cada mes |
| month | 3 | Cada 3 meses (trimestral) |
| year | 1 | Cada año |
El período de facturación máximo es de 1 año. Por ejemplo, intervalCount no puede superar 365 para day, 52 para week, 12 para month, ni 1 para year.
Los intervalos minute y hour solo están disponibles en modo de prueba — útiles para probar rápidamente tu integración sin esperar ciclos de facturación reales.
Periodos de prueba
Puedes ofrecer un periodo de prueba gratuito antes del primer cobro. Configúralo con una de las siguientes opciones:
- trialPeriodDays — número de días gratuitos (p. ej.,
14para un periodo de prueba de 14 días) - trialPeriodEnd — marca de tiempo Unix cuando finaliza el periodo de prueba
Durante la activación, MONEI crea un pago de verificación de €0 para validar el método de pago del cliente sin cobrarle. El primer cobro real se realiza cuando finaliza el periodo de prueba.
Puedes ampliar un periodo de prueba activo actualizando trialPeriodEnd en una suscripción en estado TRIALING — consulta Actualizar detalles de la suscripción.
Eventos de webhook
MONEI envía notificaciones de webhook para los cambios de estado de las suscripciones y los pagos recurrentes. Configuras dos URLs de callback separadas al crear una suscripción:
- callbackUrl — recibe los eventos de cambio de estado de la suscripción
- paymentCallbackUrl — recibe los eventos de pago de cada cobro recurrente
Eventos de suscripción
| Tipo de evento | Se activa cuando |
|---|---|
| SUBSCRIPTION_PENDING | Se crea la suscripción |
| SUBSCRIPTION_ACTIVATED | La suscripción se vuelve activa |
| SUBSCRIPTION_TRIALING | Comienza el periodo de prueba |
| SUBSCRIPTION_PAUSED | La suscripción se pausa |
| SUBSCRIPTION_PAST_DUE | Un pago recurrente falla |
| SUBSCRIPTION_CANCELED | La suscripción se cancela |
| SUBSCRIPTION_UPDATED | Se modifican los detalles de la suscripción |
Cada solicitud de webhook incluye una cabecera MONEI-Signature. Siempre verifica la firma antes de procesar el evento, y devuelve un código de estado HTTP 200 para confirmar la recepción.
Métodos de pago
Las suscripciones son compatibles con los siguientes métodos de pago:
- Tarjeta — Visa, Mastercard y otras redes de tarjetas compatibles. Método de pago predeterminado para todas las suscripciones.
- Bizum — Disponible con las siguientes restricciones:
- Solo intervalos de facturación mensual y anual (los intervalos diario y semanal no están disponibles en producción)
- Los periodos de prueba no están disponibles
- El importe de la suscripción no puede modificarse tras la activación
Enviar enlace de suscripción
Puedes enviar un enlace de activación al cliente por correo electrónico o SMS usando el endpoint enviar enlace de suscripción. Esto permite al cliente activar la suscripción sin ninguna integración personalizada — útil para la creación manual o desde el back office.
Consulta Enviar enlace de suscripción para más detalles.
Próximos pasos
Elige cómo integrar las suscripciones según tus necesidades:
- Usar página de pago prediseñada — Redirige a los clientes a una página alojada por MONEI para activar su suscripción. La integración más sencilla, no se requiere código de frontend.
- Crear un checkout personalizado — Recoge los detalles de pago en tu propio sitio usando los componentes de MONEI. Control total sobre la experiencia de checkout.
- Gestionar suscripciones — Pausa, reanuda, cancela, omite pagos, actualiza el método de pago y mucho más.
- Gestionar pagos fallidos — Comprende la lógica de reintentos, configura el comportamiento de dunning y recupera suscripciones en estado vencido.