Overview

The Recurring Module is a low-code alternative to managing Credential on File and building your own subscription billing logic.

Instead of designing and maintaining CIT/MIT workflows, retry handling, and billing schedulers, you can use the Recurring Module to configure automated, repeat charges. The gateway will handle submitting transactions for you, based on the subscriptions you have configured.

Every recurring billing configuration consists of two core objects that allow you to define billing rules once and apply them to multiple customers.

Alternatively, you can define custom subscriptions, which are not connected to a preexisting plan. Custom subscriptions require both the billing terms and payment details to be provided. Further instructions regarding setting up custom subscriptions can be found in the Quick Start Guide below.

Use the Recurring Module when:

• You need predictable, scheduled billing such as memberships or subscriptions
• You want to avoid building custom recurring billing infrastructure
• You prefer a gateway-managed solution rather than maintaining your own Credential on File logic

The Recurring Module provides a streamlined path to launch with minimal development overhead.

If you require full control over billing orchestration within your platform, you can store payment credentials and trigger transactions directly via the API. For greater flexibility, refer to the Credential on File guide.

⚠️

The Recurring Module is available only in regions that are not subject to PSD2 regulations. For customers in the UK/EU and other PSD2-mandated regions, please refer to the Credential on File guide.

❗️

On Sandbox accounts, the Recurring Module will not submit transactions. Plans and subscriptions can be created, but no actual transactions will be processed.

Quick Start Guide

Welcome to the Recurring Module integration guide. Follow the steps below to set up recurring plans and subscriptions to be handled by the gateway's built-in recurring system.

Step 1: Create a Plan

You can create a plan with the desired billing configuration using the V5 API like in the example below:

curl --request POST   
--url https://sandbox.nmi.com/api/v5/plans \
--header 'Authorization: YOUR_API_KEY' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
  "id": "string",
  "plan_name": "string",
  "plan_amount": 0,
  "plan_payments": 0,
  "month_frequency": 1,
  "day_of_month": 1
}
'

For further API details, see the Create Plan section in the API Reference. You can also create plans within the Merchant Portal by navigating to Recurring -> Add Plan.

Step 2: Create a Subscription

Create a subscription for the customer and associate it with the previously created plan using the V5 API:

curl --request POST   
--url https://sandbox.nmi.com/api/v5/subscriptions \
--header 'Authorization: YOUR_API_KEY' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
  "plan_id": "string",
  "payment_details": {
    "card_number": "string",
    "card_exp": "string",
    "card_cvv": "string"
  }
}
'

After setup, the Recurring Module handles the ongoing transaction scheduling and processing.

For further API details, see the Create Subscription section in the API Reference. You can also create subscriptions within the Merchant Portal by navigating to Recurring -> Add Subscription.

Step 3: Create a Custom Subscription (Optional Step)

Create a custom subscription if you do not want to associate a subscription with a previously created plan using the V5 API. This requires the billing configuration to be provided.

curl --request POST   
--url https://sandbox.nmi.com/api/v5/subscriptions \
--header 'Authorization: YOUR_API_KEY' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
  "plan_amount": 0,
  "plan_payments": 0,
  "month_frequency": 1,
  "day_of_month": 1,
  "payment_details": {
    "card_number": "string",
    "card_exp": "string",
    "card_cvv": "string"
  }
}
'

After setup, the Recurring Module handles the ongoing transaction scheduling and processing.

For further API details, see the Create Subscription section in the API Reference. You can also create subscriptions within the Merchant Portal by navigating to Recurring -> Add Subscription (select "Create a New Billing Plan" instead of using an existing plan).

Step 4: Create a Subscription Using the Customer Vault (Optional Step)

If you also have the Customer Vault enabled, you can use a previously-created Customer Vault record to create a subscription or custom subscription.

curl --request POST   
--url https://sandbox.nmi.com/api/v5/subscriptions \
--header 'Authorization: YOUR_API_KEY' \
--header 'accept: application/json' \
--header 'content-type: application/json' \
--data '
{
  "plan_id": "string",
  "customer_vault_id": "string"
}
'

After setup, the Recurring Module handles the ongoing transaction scheduling and processing.

For further API details, see the Create Subscription section in the API Reference. You can also do this within the Merchant Portal by navigating to Customer Vault -> List Customers, then find the specific Customer Vault record and click "Create Recurring Subscription".

Step 5: Set up Webhooks (Optional Step)

Recurring billing events can trigger webhook notifications so your platform stays in sync.

Common use cases include:

• Updating subscription status in your system
• Notifying customers of billing changes
• Syncing billing data with reporting tools

See the Recurring Events guide for full webhook details and event payloads.

Note that transactions ran by the Recurring Module will trigger the "transaction.sale" webhook events.