Subscriptions with prebuilt payment page

Redirect customers to a MONEI-hosted payment page to activate their subscription. This is the simplest way to start collecting recurring payments — no frontend code required.

Before You Begin

• You need a MONEI account and your API key (test or live).
• Use your test mode keys during development.
• Ensure at least one payment method is enabled in your account settings.

How It Works

1. Your backend creates a subscription with amount, currency, and billing interval
2. The subscription is activated, returning a redirectUrl for the initial payment
3. The customer is redirected to the MONEI-hosted payment page
4. The customer completes the initial payment (including 3D Secure if required)
5. After payment, the customer is redirected back to your completeUrl
6. MONEI sends webhooks for both the initial payment and subscription status changes — recurring payments are charged automatically at each billing interval

Integration Steps

1. Create a subscription (Server-side)

Create a Subscription on your server with the billing amount, currency, and interval.

cURL

POST https://api.monei.com/v1/subscriptions

curl --request POST 'https://api.monei.com/v1/subscriptions' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "amount": 1500,
  "currency": "EUR",
  "interval": "month",
  "intervalCount": 1,
  "description": "Pro Plan Monthly",
  "customer": {
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "callbackUrl": "https://example.com/subscriptions/callback",
  "paymentCallbackUrl": "https://example.com/payments/callback"
}'

(Replace YOUR_API_KEY with your actual MONEI API key)

Node.js

server.js

import {Monei} from '@monei-js/node-sdk';

// Replace YOUR_API_KEY with your actual MONEI API key
const monei = new Monei('YOUR_API_KEY');

const subscription = await monei.subscriptions.create({
  amount: 1500,
  currency: 'EUR',
  interval: 'month',
  intervalCount: 1,
  description: 'Pro Plan Monthly',
  customer: {
    name: 'John Doe',
    email: 'john.doe@example.com'
  },
  callbackUrl: 'https://example.com/subscriptions/callback',
  paymentCallbackUrl: 'https://example.com/payments/callback'
});

// You will need the subscription id in the next step
const subscriptionId = subscription.id;

PHP

server.php

<?php
require_once 'vendor/autoload.php';

use Monei\MoneiClient;
use Monei\Model\CreateSubscriptionRequest;
use Monei\Model\PaymentCustomer;

// Replace YOUR_API_KEY with your actual MONEI API key
$monei = new MoneiClient('YOUR_API_KEY');

$subscription = $monei->subscriptions->create(
  new CreateSubscriptionRequest([
    'amount' => 1500,
    'currency' => 'EUR',
    'interval' => 'month',
    'interval_count' => 1,
    'description' => 'Pro Plan Monthly',
    'customer' => new PaymentCustomer([
      'name' => 'John Doe',
      'email' => 'john.doe@example.com'
    ]),
    'callback_url' => 'https://example.com/subscriptions/callback',
    'payment_callback_url' => 'https://example.com/payments/callback'
  ])
);

// You will need the subscription id in the next step
$subscriptionId = $subscription->getId();
?>

Python

server.py

import Monei
from Monei import CreateSubscriptionRequest, PaymentCustomer

# Replace YOUR_API_KEY with your actual MONEI API key
monei = Monei.MoneiClient(api_key="YOUR_API_KEY")

subscription = monei.subscriptions.create(
    CreateSubscriptionRequest(
        amount=1500,
        currency="EUR",
        interval="month",
        interval_count=1,
        description="Pro Plan Monthly",
        customer=PaymentCustomer(
            name="John Doe",
            email="john.doe@example.com"
        ),
        callback_url="https://example.com/subscriptions/callback",
        payment_callback_url="https://example.com/payments/callback"
    )
)

# You will need the subscription id in the next step
subscription_id = subscription.id

Key parameters:

• amount positive integer — Amount in the smallest currency unit (e.g., 1500 = €15.00).
• currency string — Three-letter ISO currency code (e.g., EUR).
• interval string — Billing interval: day, week, month, or year.
• intervalCount number — Number of intervals between each charge (e.g., 3 with month = quarterly).
• callbackUrl string — URL that receives subscription status change webhooks.
• paymentCallbackUrl string — URL that receives payment webhooks for each recurring charge.

Check all available request parameters.

2. Activate the subscription (Server-side)

Activate the subscription to start the billing process. The response includes a redirectUrl to send the customer to the MONEI-hosted payment page.

cURL

POST https://api.monei.com/v1/subscriptions/{id}/activate

curl --request POST 'https://api.monei.com/v1/subscriptions/YOUR_SUBSCRIPTION_ID/activate' \
--header 'Authorization: YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '{
  "completeUrl": "https://example.com/checkout/complete"
}'

(Replace YOUR_SUBSCRIPTION_ID and YOUR_API_KEY)

Node.js

server.js

const activation = await monei.subscriptions.activate('YOUR_SUBSCRIPTION_ID', {
  completeUrl: 'https://example.com/checkout/complete'
});

// Redirect the customer to this URL
const redirectUrl = activation.nextAction.redirectUrl;

PHP

server.php

<?php
use Monei\Model\ActivateSubscriptionRequest;

$activation = $monei->subscriptions->activate(
  'YOUR_SUBSCRIPTION_ID',
  new ActivateSubscriptionRequest([
    'complete_url' => 'https://example.com/checkout/complete'
  ])
);

// Redirect the customer to this URL
$redirectUrl = $activation->getNextAction()->getRedirectUrl();
?>

Python

server.py

from Monei import ActivateSubscriptionRequest

activation = monei.subscriptions.activate(
    "YOUR_SUBSCRIPTION_ID",
    ActivateSubscriptionRequest(
        complete_url="https://example.com/checkout/complete"
    )
)

# Redirect the customer to this URL
redirect_url = activation.next_action.redirect_url

The activation response is a Payment object for the initial charge. Redirect the customer to nextAction.redirectUrl.

Check all available request parameters.

3. Customer completes the payment

The customer enters their payment details on the MONEI-hosted payment page and completes any required 3D Secure verification.

4. Customer is redirected back to your site

The customer is redirected to completeUrl with payment_id and subscription_id query parameters.

Use the get payment endpoint to check the initial payment status, and the get subscription endpoint to verify the subscription status (it should be ACTIVE or TRIALING).

note

Do not rely solely on the redirect to confirm the payment — always use the webhook (next step) as the authoritative source of truth.

5. Handle webhooks (Server-side)

MONEI sends two types of webhook notifications:

• Payment callback — sent to paymentCallbackUrl for the initial payment and each recurring charge. The request body contains the full Payment object.
• Subscription callback — sent to callbackUrl when the subscription status changes (e.g., PENDING → ACTIVE). The request body contains the full Subscription object.

Each request includes a MONEI-Signature header. Verify this signature to confirm the request is from MONEI, and return a 200 HTTP status code to acknowledge receipt.

If MONEI does not receive a 200 response, the notification will be retried.

Before You Go Live

• Switch to your live mode API key.
• Ensure your payment methods are enabled in live mode.
• Test your webhook endpoints handle both payment and subscription callbacks correctly.

Test mode limits

In test mode, subscriptions have the following limits:

• Maximum 3 active subscriptions per account
• Subscriptions are auto-canceled after 12 payments
• Minute and hour billing intervals are available for faster testing