Chapter 7 - Subscriptions

Nuvei Subscriptions is a versatile and complete recurring payments solution. It can be used in two main ways:

Automatic payments - This is a fully automated solution that will manage the lifetime of a recurring payment once it is registered and notify the merchant of any issues that happen during it's lifetime.

Manual payments – With this solution, recurring payments are set up in our system just as they are for automatic payments. The main diference is that our system does not actually process payments automatically. Instead, when a payment is pending, the merchant should initiate the payment, either via and “XML Subscription ACH Payment” or through the SelfCare System. Another diference with this method is that you can modify the amount of the payment.

Subscriptions can only be set up on account details already stored in our system using the SecureACH feature above. Subscriptions are set up in two levels:

Stored Subscriptions – Stored subscriptions are not subscriptions in their own right, but instead are templates for multiple subscriptions that are registered under them. They defne the period (weekly / monthly / quarterly / annually), the number of those periods (if it's a fxed number), setup price, recurring price, etc. They are intended to represent a product, for example.

Subscriptions – Every subscription set up has to be under a Stored Subscription. However some of the settings of the stored subscription can be overruled by the Subscription itself, as you will see below. Subscriptions are intended to represent a specifc order of a product represented by the stored subscription that it's under.

New Subscription can be registered from the Nuvei hosted page. When new subscription is created it name, description, set- up price, recurring price, length, period type and type are copied from the corresponding stored subscription,

To get Subscription Registration Page opened in a client browser a POST must be made to the following URL:

https://testpayments.nuvei.com/merchant/subscriptionpage/register

Subscription registration POST parameters description:

Field Name

Required

Description

MERCHANTREF

Y

Unique Merchant Reference. Length is limited to 48 chars.

TERMINALID

Y

A TerminalID provided by Nuvei. NB – Please contact Nuvei to be

issued with a test terminal ID.

FieldName

Required

Description

STOREDSUBSCRIPTIONREF

N

This feld is required if new Subscription being created should be based on already existing Stored Subscription.

SECUREACHACCOUNTMERCHANTR EF

Y

Merchant Reference of a SecureACH record which will be used to do

set-up and recurring payments. (Only one of SECUREACHACCOUNTMERCHANTREF or ACHREFERENCE must bepresent)

ACHREFERENCE

Y

ACH Account secure reference generated by NetTraxion and provided to merchant during creation Secure ACH Account. (Only one of SECUREACHACCOUNTMERCHANTREF or ACHREFERENCE must be present)

SUBSCRIPTIONRECURRINGAMOUN T

SUBSCRIPTIONINITIALAMOUNT

N

N

The monthly recurring amount for Automatic subscriptions. Will override the Stored Subscription value if populated.

The setup payment amount. This will be authorised in real time and the usbscription will only be successfully set up if it approves. Will override the Stored Subscription value if populated.

DATETIME

Y

Format: DD-MM-YYYY:HH:MM:SS:SSS.

STARTDATE

Y

Subscription Start Date. Format: dd-MM-yyyy

ENDDATE

N

Subscription End Date, if it is not set subscription will continue until manually canceled or lenght reached (if it is set).

HASH

Y

An SHA-512 HASH. See Note 1 below.

Following parameters should be posted if new Stored Subscription should be created (STOREDSUBSCRIPTIONREF shouldn't be posted in such case).

NEWSTOREDSUBSCRIPTIONREF

Y

Merchant Ref to be assigned for new Stored Subscription being created

NAME

Y

Display name for subscription.

DESCRIPTION

Y

Description explaining subscription.

PERIODTYPE

N

Integer code of Period Type, can be:

2- WEEKLY

3- FORTNIGHTLY

4- MONTHLY

5- QUARTERLY

6- YEARLY

FieldName

Required

Description

LENGTH

Y

0 for non ending / multiplier of period. This does not take efect if

(Subscription length * Period Type) >i (End Date – Current Date).

RECURRINGAMOUNT

Y

Cost of each payment (will be ignored if manual).

INITIALAMOUNT

Y

Initial (set-up) payment to be taken of card. Payment will not be taken if it is 0. Setup fails if setup payment declines.

Assuming valid details were sent, the Subscription Registration Hosted page will be displayed, clicking on “Accept & Subscribe” button will create the subscription only if the setup amount authorises successfully, and the resulting GET parameters will be forwarded to the Subscription Receipt URL that is confgured on the Terminal Setup page.

Following parameters will be sent to the Subscription Receipt URL:

FieldName

Description

RESPONSECODE

Response Code:

• A - Approval

• C - Cancelled

Check the Error: Reference source not found table for a full list of supported codes.

RESPONSETEXT

Response Text. MERCHANTREF

Original Merchant Reference. DATETIME

Format: DD-MM-YYYY:HH:MM:SS:SSS.

HASH

An SHA-512 HASH. See Note 1 below.

Notes:

1. The SHA-512 HASH is generated using the following as an input string:

TERMINALID:MERCHANTREF:DATETIME:RESPONSECODE:RESPONSETEXT:secret

if invalid parameter values will be sent, an Error Page will appear and the web browser will not be redirected to the Subscription Receipt Page. This should not happen in a production environment after integration is completed.

Each subscription should be created based on some stored subscription. When new subscription is created it name,
description, set-up price, recurring price, length, period type and type are copied from the corresponding stored subscription,
most subscription felds can be changed by Subscription Updating request.

To create new subscription based on an existing Stored Subscription following XML Gateway request should be sen

If Stored Subscription doesn't yet exist it can be created putting all it details into the nested
NEWSTOREDSUBSCRIPTIONINFO tag, STOREDSUBSCRIPTIONREF in such case should be omitted. There is example of such
request:

Stored Subscription Merchant Reference, it is allowed only if
NEWSTOREDSUBSCRIPTIONINFO do not present.

SECUREACHACCOUNTMERCH
ANTREF

N

Merchant Reference of a Secure ACH Account which will be used to
do set-up and recurring payments.(Only one of
SECUREACHACCOUNTMERCHANTREF or ACHREFERENCE must be
present)

ACHREFERENCE

Y

System-Generated ACH Reference (Secure ACH).(Only one of
SECUREACHACCOUNTMERCHANTREF or ACHREFERENCE must be
present)

DATETIME

Format: DD-MM-YYYY:HH:MM:SS:SSS.

STARTDATE

Y

Subscription Start Date. Format: DD-MM-YYYY.

ENDDATE

N

Subscription End Date, if it is not set subscription will continue until
manually canceled or lenght reached (if it is set). Format: DD-MMYYYY.

NEWSTOREDSUBSCRIPTIONI
NFO

N

It is allowed only if STOREDSUBSCRIPTIONREF is not set. This tag and
all it children should be set if Stored Subscription on which new
Subscription being added should be based doesn't exists yet and should
be created. Please check NEWSTOREDSUBSCRIPTIONINFO felds
description table for details.

NOTIFICATIONLANGUAGE

N

Defnes the language which is going to be used to send the
customer's notifcation/ receipt. Acceptable values are 'EN' and 'FR'
(case sensitive).

HASH

Y

An SHA-512 HASH. See note 1 below.

Notes:

1. The SHA-512 HASH is generated using the following as an input string:
TERMINALID:MERCHANTREF:SECUREACHACCOUNTMERCHANTREF or ACHREFERENCE
:DATETIME:STARTDATE:secret

Note that Subscription MerchantRef's cannot be re-used after deletion. This is because they are tied to existing transactions
in our system and are retained internally for data integrity and issue tracing. Deleted Subscriptions can still be viewed in the
SelfCare System by using the Advanced Filter.

Manual subscription recurring payment can be done from the XML Gateway. If automatic subscription was not paid
automatically because of ACH Account details expiration or other issue it also can be paid in the same way as manual after
SecureACH issue was solved. The following is an example of a Subscription Payment request:

Errors handling

The Subscription Notifcation URL can be set in the Terminal Setup page of the SelfCare System. If this is set a POST
notifcation will be sent to this URL each time automated activity happens on any active subscriptions. Note that manual changes
applied to subscriptions via the SelfCare System will not generate these notifcations.

The data sent to the Subscription Notifcation URL contains the normal subscription response felds as well as these extra
felds:

The following felds are sent in the notifcation:

Field Name

Description

NOTIFICATIONTYPE

Possible values for subscriptions are:

SUBSCRIPTIONCREATION

SUBSCRIPTIONUPDATING

SUBSCRIPTIONDELETION

SUBSCRIPTIONSETUPPAYMENT

SUBSCRIPTIONRECURRINGPAYMENT

Possible values for stored subscriptions are:

STOREDSUBSCRIPTIONCREATION

STOREDSUBSCRIPTIONUPDATING

STOREDSUBSCRIPTIONDELETION

TERMINALID

The Terminal ID that the subscription is set up on.

ORDERID

The Order ID that the system assigned to the Subscription payment. Only sent for
SUBSCRIPTIONSETUPPAYMENT and SUBSCRIPTIONRECURRINGPAYMENT

AMOUNT

The amount of the subscription payment as a 2 digit decimal or an Integer value
for JPY amounts. Only sent for SUBSCRIPTIONSETUPPAYMENT and
SUBSCRIPTIONRECURRINGPAYMENT

Notes:

1. Subscription payments (SUBSCRIPTIONSETUPPAYMENT and SUBSCRIPTIONRECURRINGPAYMENT) SHA-512 hash is
calculated using the following as an input string: