Introduction

Nuvei provides a range of solutions that allow you to bill your customer using a series of future transactions according to some payment schedule agreement with your customer’s permission. These solutions are known by different names, subscriptions/rebilling/recurring payments/billing agreements etc.

All the solutions supported by Nuvei share some basic features:

• A subsequent (recurring) flow involves two or more transactions, an initial payment and one or more subsequent payments.
• The customer performs (or agrees to the performance of) the initial payment. This is especially significant for card payments which almost always require some form of customer presence for authentication purposes (3D-Secure, if that is applicable in your region).
• Subsequent payments are performed on behalf of the customer, according to a clearly defined payment schedule agreement, only with the customer’s permission. These transactions should only be performed using the customer’s authenticated payment credentials (UPOs), which were previously stored for use in future transactions. Customer payment methods do not need to be authenticated again for subsequent payments. These requests must be flagged as “rebilling payments”  but do not require a CVV2.

Supported Subscription Solutions

• Nuvei Rebilling Service
• Credit Card Recurring Payments via REST
• APM Recurring Payments
• External Subscription Support

Summary of Subscription Solutions

The table shows who performs each subscription step and which toolset/platform is used:

Subscription Solution	Setting Up the Nuvei Rebilling Plans and Subscriptions	Initial Payment	Subsequent Payments
Nuvei Rebilling Service	Rebilling Plans Set up by the Merchant based on: Customize an existing Rebilling Plan Create a new Rebilling Plan Using one of these ways: Nuvei Rebilling APIs Nuvei Control Panel	Not Applicable	Not Applicable
	Subscription Management Set up by: Customer – Using Payment Page. Merchant (for existing UPOs) - Using one of these ways: Nuvei Rebilling APIs Nuvei Control Panel	Customer initiates the initial payment using Nuvei Payment Page.	Nuvei sends Subsequent Payments automatically.
Merchant Manages Subscriptions	Credit Card Recurring Payments via REST The Merchant performs transactions using Nuvei REST APIs.	Customer initiates the initial payment using Nuvei REST APIs.	Merchant sends Subsequent Payments using Nuvei REST APIs.
	APM Recurring Payments The Merchant performs the recurring transaction and Nuvei links the customer’s account to the APM recurring system.	Customer initiates the initial payment using Nuvei REST APIs.	Merchant sends Subsequent Payments using Nuvei REST APIs.
	External Subscription Support The Merchant: Maintains their own ("external") subscriptions (recurring payment systems) to keep track of your customer subscriptions. Performs transactions using the Nuvei Payment Page and Nuvei REST APIs.	Customer initiates the initial payment using Nuvei Payment Page.	Merchant sends Subsequent Payments using Nuvei REST APIs.

Nuvei Rebilling Service

The Nuvei Rebilling Service allows you and your customers to set up and manage Customer Subscription Payment Plans (known as Subscriptions) to schedule and accept future customer payments. The service automatically performs recurring billing transactions on behalf of your customer, according to their Subscription.

Overview

Setting Up a Rebilling Service

Start by setting up at least one Rebilling Plan and one Subscription as described in the topics below.

• Rebilling Plans
  A Rebilling Plan is a template of potential customer subscription conditions which is used as the basis for creating individualized Customer Subscription Payment Plans.
  For details, see the Rebilling Plan topic below.
• Subscriptions
  A Subscription (Customer Subscription Payment Plan) is a contract between you and your customer that specifies individualized subscription conditions and authorizes you to collect customer payments by sending (recurring) payment requests on behalf of the customer.
  For details, see the Subscription topic below.

Sending the Subsequent Recurring Payments

• Sending (Recurring) Payment Requests
  After the initial payment is successfully completed and the encrypted card details are safely stored in the Nuvei system, the Rebilling Service becomes responsible for scheduling and performing the Subsequent Recurring Payment requests (with no need for the customer to be “present”), according to the Subscription’s conditions.
  For details, see the Using the Rebilling Service topic below.
• “Card Updater” Features
  The Rebilling Service also incorporates “Card Updater” features provided by card schemes (for certain supported cards). From time to time, card issuers notify Nuvei of changes in customer card details, and Nuvei updates its databases accordingly. This helps to ensure a high level of frictionless payment processing for existing subscriptions.

Rebilling Plan Templates

A Rebilling Plan is a flexible template of potential customer subscription conditions, which is used as the basis for creating individualized Customer Subscription Payment Plans.

You can create, edit, and delete Rebilling Plan templates via your Nuvei Control Panel, or by using our REST API methods:

• Control Panel
  For details on how to create, modify, and delete Rebilling Plans using your Nuvei Control Panel, see the Recurring Plans Report.
  Viewing existing Rebilling Plans also allows you to drill down to the details of all transactions for that plan.
• Rebilling APIs
  Nuvei provides the following REST APIs for you to set up and manage Rebilling Plans, as described in these topics:
  • /createPlan
    Creating a charging plan to set timing and payment conditions for a certain product or service.
  • /editPlan
    Editing the charging or timing conditions of a certain Rebilling Plan.
  • /getPlansList
    Retrieve information for an existing plan.

Subscription Management

Subscriptions are “subscription payment contracts” between you and your customer that specify the payment method, individualized subscription conditions, amounts, payment dates, etc.

A Subscription authorizes you to collect customer payments on behalf of your customer, using (recurring) payment requests.

The following topics are discussed below:

• Creating Subscriptions
  • Customer – Using the Nuvei Payment Page
  • Merchant – Using the REST API Methods
  • Merchant – Using the Control Panel
• Managing Subscriptions
  • Merchant – Using the Control Panel
  • Merchant – Rebilling APIs

Creating Subscriptions

Subscriptions are based on a Rebilling Plan template (identified by its planId) which contains subscription conditions that can be customized for individualized Subscriptions.

A Subscription can be created by you or by your customer in these ways, as described below:

• Customer Creates the Subscription 
  • Customer – Using the Nuvei Payment Page
• Merchant Creates the Subscription
  
  A merchant can only create a subscription if all these conditions are met:

  • They must use a pre-existing UPOs (previously stored payment methods).
  • The customer must give their permission.
    For example, when your customer agrees to renew/extend an existing Subscription. In that case, the initial subscription payment from the original Subscription is considered the initial payment of the new Subscription.

  If the above conditions are met, you can create Subscriptions in these ways:
  

  • Merchant – Using the REST API Methods
  • Merchant – Using the Control Panel

Customer – Using the Nuvei Payment Page

Your customer can use the Nuvei Payment Page to create a recurring Subscription for themselves.

1. Display a list of the available Rebilling Plan templates to your customer, so they can select a plan on which to base their new Subscription.
2. Prompt the customer to enter their payment method details, or choose a previously saved payment method (UPO).
3. If you want, you can allow the customer to customize the subscription plan details.

For full details, see the /createSubscription topic.

Example Payment Page (Cashier) /purchase Request

The /purchase request (below), which you create for the Payment Page (Cashier) request, shows the planId (marked in red) of the Rebilling plan template upon which this particular Subscription is based:

https://ppp-test.safecharge.com/ppp/purchase.do?merchant_id=5121528327976171922&merchant_site_id=137723&user_token=auto&user_token_id=Test_7617159594&item_open_amount_1=false&item_min_amount_1=1&item_max_amount_1=100&item_name_1=Cashier%20Test%20product%201&item_amount_1=1.23&item_quantity_1=1&total_amount=1.23&currency=EUR&version=4.0.0&first_name=test&last_name=test&address1=test&city=test&zip=123456&country=GB&phone1=123456&[email protected]&payment_method=cc_card&userid=test1234&planId=4459&time_stamp=2021-09-12.17:18:37&checksum=a655a5d5b5becfc1c85891c9b8df639abfad297b366ff038efaa18bbf4868141

Example Payment Page (Cashier) Desktop Request

Example Payment Page (Cashier) Response

Example Payment Page (Cashier) Mobile Request

Example Payment Page (Cashier) Response

Merchant – Using the REST API Methods

The subscription parameters are defaulted from the Rebilling Plan which you choose as the template for the subscription. However, you can override any of these parameters dynamically during the creation of the Subscription.
(To use the following advanced APIs, please contact the Nuvei Integration Team for advice on how to use them.)

• /createSubscription
  Creating a customer Subscription to perform future recurring transactions.
• /editSubscription
  Editing the payment or recurring conditions of a certain Subscription.

Merchant – Using the Control Panel

The easiest way to use the Rebilling Service is via your Nuvei Control Panel: Recurring Subscriptions – You can create subscriptions.

Managing Subscriptions

Nuvei provides flexible tools for you to modify, extend, and cancel Subscriptions using the Nuvei Control Panel, or via our Rebilling API methods, as described below:

• Merchant – Using the Control Panel
• Merchant – Rebilling APIs

Merchant – Using the Control Panel

The easiest way to use the Rebilling Service is via your Nuvei Control Panel: Recurring Subscriptions – You can modify and delete Subscriptions. Viewing existing Subscriptions also allows you to drill down to the details of all transactions for that Subscription.

Merchant – Rebilling APIs

Nuvei provides the following REST APIs for you to manage Subscriptions:

• /getSubscriptionsList
  Retrieve information for an existing Subscription.
• /cancelSubscription
  Cancel an existing Subscription.

Using the Rebilling Service

The most popular way to use the Nuvei Rebilling Service is where your customer uses the Payment Page UI to set up their own Subscriptions, as described in the following steps:

1. Start by setting up a Rebilling Plan to offer your customers.
   (The easiest way to set up and manage the Nuvei Rebilling Service is via your Nuvei Control Panel.)
2. Allow the customer to select one of the available Rebilling Plans, for use as the basis of their individualized Customer Payment Subscription.
3. Prompt the customer to enter their payment method details, or choose a previously saved payment method (UPO).
4. If you want, you can give the customer an opportunity to customize the subscription conditions defaulted by the Rebilling Plan.
5. The customer “accepts” the subscription details (with or without customizations) and the Subscription is stored.
   
6. Use the payment method details to perform the initial payment (while the customer is still present). The initial subscription payment is sent for processing (on the gateway) on the “initial payment date”.
7. After the initial payment is completed successfully:
   • If a UPO was not used, then Nuvei stores the customer’s payment method details in a UPO (user payment option) record, for use in future subscription payments (on behalf of the customer).
   • The Nuvei system becomes responsible for scheduling and performing the remaining Subsequent Recurring Payments (with no need for the customer to be “present”).
     Nuvei automatically sends the Subsequent Recurring Payment requests to an acquirer for processing, according to the Subscription’s conditions. These requests are flagged as “rebilling payments” and contain a UPO but do not require a CVV2.
8. After a successful recurring payment (either an initial payment or a subsequent payment), you receive a DMN with dmnType subscription or subscriptionPayment.
   
   

   Example Subscription DMN

   'dmnType' => 'subscription',
   'merchant_id' => 111111222222333333,
   'merchant_site_id' => 1111111,
   'subscriptionId' => '123123',
   'subscriptionState' => 'ACTIVE',
   'planId' => '12345',
   'templateId' => '123456',
   'productId' => '12345',
   'productName' => 'Rebilling Plan',
   'userPaymentOptionId' => '101956858',
   'upoRegistrationDate' => '20240111',
   'payment_method' => 'cc_card',
   'nameOnCard' => 'Cardholder',
   'expMonth' => '11',
   'expYear' => '25',
   'Token' => 'awAxADEARgBkAEYAZABuADAAZABkAGQAagBVADgAagA3AGoASwBHAHoAbwAmAEgAKQBHAGUAcQBNAEgAUQBLAD8AcABRAHgATQArAFQAYQB3AHQAJQBAACsASwB2ADUAUQAsAEoAMwA=',
   'cardNumber' => '4****1111',
   'cardType' => 'visa',
   'uniqueCC' => '4E+K4R18rBmltRfq9OHSG65FHXA=',
   'bin' => '476134',
   'lastFourDigits' => '1111',
   'user_token_id' => 'UserToken',
   'email' => '[email protected]',
   'country' => 'United Kingdom',
   'responseTimeStamp' => '2024-01-12.08:29:07',
   'responsechecksum' => 'e9ea781f100e013f3270848cb9fb64e40da956ba40259ff93967aa1ce6366e7f',

9. Authenticate the DMN.

Authenticating the DMN

Subscription DMNs include a responsechecksum that merchants can use to verify Nuvei sent the DMN and that it was not manipulated by any external parties.

To authenticate a subscription DMN:

1. Concatenate into a string all of the parameter values in the DMN in the exact order that they are sent.
2. Add merchantSecretKey to the end of that string.
3. Encrypt the entire string with SHA-256 or MD5, depending on the SiteId configuration.
   Use encoding passed from the merchant site to create the encryption. The default encoding is UTF-8 (unless the encoding input parameter specifies otherwise).
4. Compare the result to the responsechecksum in the DMN. If they match, Nuvei sent the DMN.

For the example subscription DMN above, the string before encryption is:

subscription1111112222223333331111111123123ACTIVE1234512345612345Rebilling Plan10195685820240111cc_cardCardholder1125awAxADEARgBkAEYAZABuADAAZABkAGQAagBVADgAagA3AGoASwBHAHoAbwAmAEgAKQBHAGUAcQBNAEgAUQBLAD8AcABRAHgATQArAFQAYQB3AHQAJQBAACsASwB2ADUAUQAsAEoAMwA=4****1111visa4E+K4R18rBmltRfq9OHSG65FHXA=4761341111UserTokentest@test.comUnited Kingdom2024-01-12.08:29:07[merchantSecretKey]

After SHA-256 encryption, the responsechecksum should be and is:

e9ea781f100e013f3270848cb9fb64e40da956ba40259ff93967aa1ce6366e7f

If a Recurring Payment Fails

To ensure a smooth subscription experience for both merchants and customers, Nuvei has included a “retry mechanism” in the Rebilling Service.

1. If a recurring payment is declined (transaction status "Declined"):
   • You receive a Retry Subscription Payment DMN callback notification.
   • The “retry mechanism” is initiated.
2. The first retry:
   • The first retry is performed 72 hours after the initial decline.
   • If this retry fails:
     • You receive a Retry Subscription Payment DMN callback notification.
3. The second retry:
   • The second retry is performed 72 hours after the second decline.
   • If this retry fails:
     • You receive a Retry Subscription Payment DMN callback notification.
4. The third (final) retry:
   • A third (final) retry is performed 72 hours after the third decline (72×3=216 hours after the initial decline).
   • If this final retry fails:
     • The Subscription is canceled (Subscription status is changed to "Inactive").
     • You receive a Retry Subscription Cancelled DMN callback notification.

Merchant Manages Subscriptions

You can perform recurring payments in these ways, as described below:

• Recurring Payments via REST
• APM Recurring Payments
• External Subscription Support

Credit Card Recurring Payments via REST

Use the Merchant-Initiated Transaction (MIT) flow, which involves at least two transactions, an initial payment, followed by one or more subsequent payments.
Refer to these topics for details:

• Initial MIT Payment (Initiated by a customer).
• Subsequent MIT Payments (Initiated by the merchant with the customer’s prior consent using the customer’s stored credentials).

APM Recurring Payments

Some APM providers offer recurring payment services, where after completing the initial APM payment request, subsequent (recurring) payment requests are sent directly via server-to-server, thereby eliminating the need for the customer to be involved.

To implement APM recurring payments, the input of the subMethod class changes depending on the APM scenario.

For details, see the APM subMethod Class.

External Subscription Support

This solution allows you to:

• Use your own (“external”) subscriptions (recurring payment systems) to keep track of your customer subscriptions.
• Use Nuvei Payment Page to perform the initial subscription payment.
• Send all subsequent (recurring) transactions using Nuvei REST API methods.

Performing the Initial Payment

Redirect your customer to the Nuvei Payment Page (you should include some additional parameters in the Payment Page HTTP request) to perform the initial subscription card payment. If 3D-Secure is applicable in your region, then this “initial” transaction may include the relevant 3DS challenge functionality (which complies with the SCA (Strong Customer Authentication) mandate and the 3D-Secure (3DS) protocol).

For full details see the External Subscription Support topic.

All Subsequent (Recurring) Payments

You can send all the subsequent (recurring) transactions using Nuvei REST API methods.

For details, see the Submit Subsequent MIT Payments – For Payments Originally Initiated by Nuvei topic.