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. |
En MONEI Dashboard → Suscripciones, cada estado es una pestaña sobre la tabla, así que puedes listar todas las suscripciones activas, en prueba, en pausa, canceladas o con pago pendiente:
Intervalos de facturación
Configura la frecuencia con la que se cobra al cliente usando interval e intervalCount. La tabla siguiente muestra ejemplos habituales; no es una lista completa de todos los intervalos de facturación válidos:
| 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.
Puedes cambiar el intervalo de una suscripción activa. Se aplica desde el siguiente periodo de facturación, o desde ahora si prorrateas el cambio.
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
Hay dos formas de seguir una suscripción. Usa una de ellas o las dos.
- Callbacks de suscripción. Define estas dos URLs al crear una suscripción:
callbackUrlrecibe el objeto Subscription (no un sobre de evento) cuando cambia el estado de la suscripción, y de nuevo tras cada reintento de pago fallido. Lee su campostatuspara saber el nuevo estado.paymentCallbackUrlrecibe el objeto Payment de cada cobro recurrente.
- Webhooks de cuenta. Selecciona los tipos de evento
subscription.*en Panel → Configuración → Webhooks. Cada entrega es un sobre de evento, y sutypeindica qué ha ocurrido.
Eventos de suscripción
| Evento del webhook de cuenta | Se activa cuando | status enviado a callbackUrl |
|---|---|---|
subscription.pending | Se crea la suscripción | No se envía |
subscription.trialing | Comienza el periodo de prueba | TRIALING |
subscription.activated | La suscripción pasa a estar activa | ACTIVE |
subscription.paused | La suscripción se pausa | PAUSED |
subscription.past_due | Un pago recurrente falla | PAST_DUE |
subscription.canceled | La suscripción se cancela | CANCELED |
subscription.updated | Se modifican los detalles de la suscripción | No se envía |
En la API GraphQL, los mismos tipos de evento se escriben en mayúsculas, por ejemplo SUBSCRIPTION_ACTIVATED.
Cada solicitud incluye una cabecera MONEI-Signature. Siempre verifica la firma antes de procesarla, 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 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
- Los cambios no se pueden prorratear
Activar suscripciones
Elige cómo activan los clientes las suscripciones:
- Página de pago alojada — Redirige a los clientes a la página de pago alojada de 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.
- Enviar enlace de suscripción — Envía un enlace de activación por email o SMS para crear suscripciones de forma manual o desde el back office.
Gestionar suscripciones
Cuando las suscripciones estén activas, usa estas guías para gestionarlas:
- Gestionar suscripciones — Pausa, reanuda, cancela, omite pagos, actualiza el método de pago, prorratea cambios de plan y mucho más.
- Gestionar pagos fallidos — Comprende la lógica de reintentos, configura el comportamiento de y recupera suscripciones en estado vencido.
Preguntas frecuentes
¿Qué es la API de Suscripciones?
La API de Suscripciones te permite cobrar a un cliente un importe fijo con una periodicidad regular. Al crear la suscripción defines el importe, la divisa, el intervalo, el periodo de prueba y los datos del cliente, y MONEI cobra en cada periodo de facturación. Los usos habituales son cajas por suscripción, cuotas de socio, cursos online y de alquileres.
¿Qué pasa cuando falla el pago de una suscripción?
La suscripción pasa a PAST_DUE y MONEI reintenta el cobro según un calendario: por defecto, 1, 6 y 15 días después del fallo en una suscripción mensual. Si fallan todos los reintentos, la suscripción se cancela. Consulta Gestionar pagos fallidos.
¿Puedo definir mi propio calendario de reintentos?
Sí, con el parámetro retrySchedule. Todos los reintentos deben producirse dentro de un intervalo de facturación. Consulta Calendario de reintentos personalizado.
Suscripciones en WooCommerce
El plugin de WooCommerce para MONEI incluye la opción de suscripciones. Antes de configurar las suscripciones en tu cuenta de WooCommerce, tendrás que instalar y configurar el plugin de WooCommerce para MONEI, y a continuación, comprar la extensión de WooCommerce Subscriptions.