Subscriptions integration

Subscriptions allow you to charge a customer on a recurring basis.

Integration

1. Create a new subscription on your server.

cURL
Node.js
PHP
Python

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 '{
  "customer": {
    "name": "John Doe",
    "email": "john.doe@monei.com"
  },
  "amount": 110,
  "currency": "EUR",
  "interval": "month",
  "intervalCount": 1,
  "description": "MoonMail Lite Monthly",
  "callbackUrl": "https://example.com/subscription/callback",
  "paymentCallbackUrl": "https://example.com/payment/callback"
}'

(Replace YOUR_API_KEY with your actual MONEI API key)

server.js
const {Monei} = require('@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({
  customer: {
    name: 'John Doe',
    email: 'john.doe@monei.com'
  },
  amount: 110,
  currency: 'EUR',
  interval: 'month',
  intervalCount: 1,
  description: 'MoonMail Lite Monthly',
  callbackUrl: 'https://example.com/subscription/callback',
  paymentCallbackUrl: 'https://example.com/payment/callback'
});

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

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([
    'customer' => new PaymentCustomer([
      'name' => 'John Doe',
      'email' => 'john.doe@monei.com'
    ]),
    'amount' => 110,
    'currency' => 'EUR',
    'interval' => 'month',
    'interval_count' => 1,
    'description' => 'MoonMail Lite Monthly',
    'callback_url' => 'https://example.com/subscription/callback',
    'payment_callback_url' => 'https://example.com/payment/callback'
  ])
);

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

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(
        customer=PaymentCustomer(
            name="John Doe",
            email="john.doe@monei.com"
        ),
        amount=110,
        currency="EUR",
        interval="month",
        interval_count=1,
        description="MoonMail Lite Monthly",
        callback_url="https://example.com/subscription/callback",
        payment_callback_url="https://example.com/payment/callback"
    )
)

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

The following parameters are required:

amount positive integer - Amount intended to be collected by this payment. A positive integer representing how much to charge in the smallest currency unit (e.g., 100 cents to charge 1.00 USD)
currency string - Three-letter ISO currency code, in uppercase. Must be a supported currency.
interval string - Subscription interval, one of day, week, month, year
callbackUrl string - The URL will be called each time subscription status changes.
paymentCallbackUrl string - The URL will be called each time subscription creates a new payment.
intervalCount number - Number of intervals between subscription payments.

Check all available request parameters.

2. Activate the subscription.

cURL
Node.js
PHP
Python

POST https://api.monei.com/v1/subscriptions/{subscription_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",
  "cancelUrl": "https://example.com/checkout/cancel"
}'

(Replace YOUR_SUBSCRIPTION_ID and YOUR_API_KEY)

server.js
const {Monei} = require('@monei-js/node-sdk');
// Replace YOUR_API_KEY with your actual MONEI API key
const monei = new Monei('YOUR_API_KEY');
// Replace YOUR_SUBSCRIPTION_ID with the ID from the previous step
const activation = await monei.subscriptions.activate('YOUR_SUBSCRIPTION_ID', {
  completeUrl: 'https://example.com/checkout/complete',
  cancelUrl: 'https://example.com/checkout/cancel'
});

// You will need the redirectUrl from the response in the next step
const redirectUrl = activation.nextAction.redirectUrl;

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

use Monei\\MoneiClient;
use Monei\\Model\\ActivateSubscriptionRequest;

// Replace YOUR_API_KEY with your actual MONEI API key
$monei = new MoneiClient('YOUR_API_KEY');
// Replace YOUR_SUBSCRIPTION_ID with the ID from the previous step
$activation = $monei->subscriptions->activate(
  'YOUR_SUBSCRIPTION_ID',
  new ActivateSubscriptionRequest([
    'complete_url' => 'https://example.com/checkout/complete',
    'cancel_url' => 'https://example.com/checkout/cancel'
  ])
);

// You will need the redirectUrl from the response in the next step
$redirectUrl = $activation->getNextAction()->getRedirectUrl();
?>

server.py
import Monei
from Monei import ActivateSubscriptionRequest

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

# Replace YOUR_SUBSCRIPTION_ID with the ID from the previous step
activation = monei.subscriptions.activate(
    subscription_id="YOUR_SUBSCRIPTION_ID",
    request=ActivateSubscriptionRequest(
        complete_url="https://example.com/checkout/complete",
        cancel_url="https://example.com/checkout/cancel"
    )
)

# You will need the redirectUrl from the response in the next step
redirect_url = activation.next_action.redirect_url

Check all available request parameters.

3. Redirect the customer to the `redirectUrl` from the response

In the response from the activate subscription request you'll get the following response:

{
  "id": "af6029f80f5fc73a8ad2753eea0b1be0", // Payment ID
  "amount": 110,
  "currency": "EUR",
  "orderId": "84370745531439",
  "description": "Test Shop - #84370745531439",
  "accountId": "aa9333ba-82de-400c-9ae7-087b9f8d2242",
  "subscriptionId": "575bcd84-09fc-4a6e-8c4c-f88b8eb90bfa",
  "livemode": false,
  "status": "PENDING",
  "customer": {
    "email": "email@example.com",
    "name": "John Doe"
  },
  "nextAction": {
    "type": "CONFIRM",
    "mustRedirect": true, // Indicates redirection is needed
    "redirectUrl": "https://secure.monei.com/payments/af6029f80f5fc73a8ad2753eea0b1be0" // <-- REDIRECT CUSTOMER HERE
  },
  "createdAt": 1594215339
}

Redirect the customer to the nextAction.redirectUrl to show him the MONEI Hosted payment page. The response object here is actually a Payment object associated with the initial activation of the subscription.

note

As an alternative process you can confirm the payment by using monei.js on the client-side. Check our build a custom checkout guide.

4. Customer completes the payment

Customer enters the Card information and goes through the 3D secure verification process (is redirected to the page provided by the issuer bank of the Card for confirmation of the transaction) if required.

5. Customer is redirected back to your server

if customer clicks "Back to {{shop.name}}" link (you can provide shop.name in the public business details settings), s/he is redirected to cancelUrl. (Usually this url is the checkout page on your website, where the user had started a checkout process)
in any other case the customer is redirected to the completeUrl with payment_id and subscription_id query parameters. Use get payment endpoint to check the initial payment status, and get subscription endpoint to get the subscription status (it should move to ACTIVE or TRIALING if successful).

6. An asynchronous request is sent to your server

MONEI will notify you about the initial payment status by sending an HTTP POST request to the callbackUrl defined in the create payment step (this is the paymentCallbackUrl from the create subscription request). The request body will contain the full Payment object.

Additionally, MONEI will notify you about the subscription status changes (e.g., from PENDING to ACTIVE) by sending an HTTP POST request to the callbackUrl defined in the create subscription request. The request body will contain the full Subscription object.

This ensures that you get the status updates even when the customer closes the browser window or loses Internet connection.

The request also contains a MONEI-Signature header. Verify this signature to confirm that the received request is sent from MONEI.

To acknowledge the receipt of the request, your endpoint must return a 200 HTTP status code to MONEI. All other response codes, including 3xx codes, indicate to MONEI that you did not receive the event.

If MONEI does not receive a 200 HTTP status code, the notification attempt is repeated. After multiple failures to send the notification over multiple days, MONEI marks the request as failed and stops trying to send it to your endpoint.

Integration​

1. Create a new subscription on your server.​

2. Activate the subscription.​

3. Redirect the customer to the redirectUrl from the response​

4. Customer completes the payment​

5. Customer is redirected back to your server​

6. An asynchronous request is sent to your server​