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. The table below shows common examples — it is not a complete list of every valid billing interval:

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.

note

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., 14 for 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 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_EXPIRED	Subscription expired (not activated in time)
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 . 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

Activating subscriptions

Choose how customers activate subscriptions:

• 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.
• Send subscription link — Send an activation link by email or SMS for manual or back-office subscription creation.

Manage subscriptions

After subscriptions are active, use these guides to manage them:

• Manage subscriptions — Pause, resume, cancel, skip payments, update payment method, and more.
• Handle failed payments — Understand retry logic, configure behavior, and recover past-due subscriptions.

Common questions

What is the Subscriptions API?

The Subscriptions API is built to help you process subscription payments. For example, use MONEI Subscriptions to set up automatic charges to your customer's account for a fixed amount on a weekly, monthly, or annual basis.

You can create subscriptions based on a range of parameters including ID, subscription name/description, starting date, amount, currency, payment method, interval, length (period-end), and customer information including shipping and billing details.

Simplify your billing, improve the customer experience, and earn recurring revenue with MONEI Subscriptions. All you have to do is integrate the Subscriptions API with your e-commerce website using the Hosted Payment Page. If your website is built on WooCommerce you can use our WooCommerce subscriptions plugin (see below).

Possible use cases include subscription boxes, subscription services (streaming, online courses, gym memberships), and for rentals or leases.

Automatic retries for subscription payments

If your customer's payment method fails during a subscription payment because the card expired (or for another reason), two things happen to recover the transaction:

1. We send an automated email to the customer asking them to update their subscription payment information. This email gets sent up to three times by default — at 1, 6, and 15 days after the failed payment for a monthly subscription (frequency depends on the subscription plan). This email comes from your business and includes your logo and contact information.
2. If the subscription payment is not recovered, it gets canceled and you will receive a notification.

You can also set up custom retries (see below).

Custom retries for subscription payments

Yes, you can determine when automatic retries for subscription payments get sent. You can schedule daily, weekly, monthly, or yearly retries, but the sum of all intervals in the retry schedule cannot exceed the subscription interval.

Examples

1. If your subscription renews weekly, and you want to send up to two retries, they both need to be sent within seven days, before the new subscription interval begins.
2. If your subscription renews monthly, and you want to send up to five retries, all five retries must occur before the next monthly subscription interval begins.

Subscriptions on WooCommerce

MONEI's WooCommerce plugin has subscription support. To configure subscriptions in your WooCommerce account, you need to first install and configure the MONEI WooCommerce plugin, then buy the WooCommerce Subscriptions extension.