Subscriptions overview
Subscriptions allow you to charge a customer on a recurring basis. MONEI handles the billing cycle automatically — you create and activate a subscription, and MONEI charges the customer at each billing interval.
Subscription lifecycle
A subscription moves through several statuses during its lifetime:
Statuses
| Status | Description |
|---|---|
| PENDING | Subscription created, awaiting activation. The customer has not yet provided a payment method. |
| TRIALING | Active trial period. A €0 verification payment was made to validate the payment method. Billing begins when the trial ends. |
| ACTIVE | Recurring payments are being charged at each billing interval. |
| PAUSED | Billing is temporarily suspended. The subscription can be resumed at any time. |
| PAST_DUE | A recurring payment failed. MONEI will retry according to the retry schedule. |
| CANCELED | The subscription has been permanently stopped. No further payments will be charged. |
| EXPIRED | The subscription was not activated in time and can no longer be used. |
Billing intervals
Configure how often the customer is charged using interval and intervalCount:
| interval | intervalCount | Billing frequency |
|---|---|---|
| day | 1 | Every day |
| week | 1 | Every week |
| week | 2 | Every 2 weeks |
| month | 1 | Every month |
| month | 3 | Every 3 months (quarterly) |
| year | 1 | Every year |
The maximum billing period is 1 year. For example, intervalCount cannot exceed 365 for day, 52 for week, 12 for month, or 1 for year.
minute and hour intervals are available in test mode only — useful for quickly testing your integration without waiting for real billing cycles.
Trial periods
You can offer a free trial before the first charge. Configure it with one of:
- trialPeriodDays — number of free days (e.g.,
14for a 14-day trial) - trialPeriodEnd — Unix timestamp when the trial ends
During activation, MONEI creates a €0 verification payment to validate the customer's payment method without charging them. The first real charge occurs when the trial period ends.
You can extend an active trial by updating trialPeriodEnd on a TRIALING subscription — see Update subscription details.
Webhook events
MONEI sends webhook notifications for subscription status changes and recurring payments. You configure two separate callback URLs when creating a subscription:
- callbackUrl — receives subscription status change events
- paymentCallbackUrl — receives payment events for each recurring charge
Subscription events
| Event type | Triggered when |
|---|---|
| SUBSCRIPTION_PENDING | Subscription is created |
| SUBSCRIPTION_ACTIVATED | Subscription becomes active |
| SUBSCRIPTION_TRIALING | Trial period starts |
| SUBSCRIPTION_PAUSED | Subscription is paused |
| SUBSCRIPTION_PAST_DUE | A recurring payment fails |
| SUBSCRIPTION_CANCELED | Subscription is canceled |
| SUBSCRIPTION_UPDATED | Subscription details are modified |
Each webhook request includes a MONEI-Signature header. Always verify the signature before processing the event, and return a 200 HTTP status code to acknowledge receipt.
Payment methods
Subscriptions support the following payment methods:
- Card — Visa, Mastercard, and other supported card networks. Default payment method for all subscriptions.
- Bizum — Available with the following restrictions:
- Monthly and yearly billing intervals only (daily and weekly not supported in production)
- Trial periods are not supported
- Subscription amount cannot be changed after activation
Send subscription link
You can send an activation link to the customer via email or SMS using the send subscription link endpoint. This allows the customer to activate the subscription without any custom integration — useful for manual or back-office subscription creation.
See Send subscription link for details.
Next steps
Choose how to integrate subscriptions based on your needs:
- Use prebuilt payment page — Redirect customers to a MONEI-hosted page to activate their subscription. Simplest integration, no frontend code required.
- Build a custom checkout — Collect payment details on your own site using MONEI Components. Full control over the checkout experience.
- Manage subscriptions — Pause, resume, cancel, skip payments, update payment method, and more.
- Handle failed payments — Understand retry logic, configure dunning behavior, and recover past-due subscriptions.