Chapter 7 - Subscriptions

Nuvei Subscriptions is a versatile and complete recurring payments solution. It can be used in two main ways:
  1. 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.
  2. 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:
  1. 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.
  2. 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.
 

7.1 Subscription Registration From the Hosted Page link

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.

 

 

Field Name

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

 

Field Name

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.

TYPE

 Y

Integer code of subscription type:

•  1 – AUTOMATIC

•  2 – MANUAL

•  3 – AUTOMATIC (WITHOUT AMOUNTS) 

ONUPDATE

 Y

Integer code of onupdate:

•  1 – CONTINUE

•  2 – UPDATE (Let all depending subscriptions fnish their subscription prior to update / Update name, description, recurringprice, setupprice, subscriptionlength, periodtype, type for all subscriptions)

ONDELETE

 Y

Integer code of ondelete:

•  1 – CONTINUE

•  2  CANCEL (Continue subscriptions until cancelled manually or reach end date or length / Cancel all subscriptions)

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

TERMINALID:MERCHANTREF:SECUREACHACCOUNTMERCHANTREF:DATETIME:STARTDATE:

secret

2. If “ACHREFERENCE ” is used, the SHA-512 HASH is generated using the following as an input string:

TERMINALID:MERCHANTREF:ACHREFERENCE :DATETIME:STARTDATE:secret

<html> <body> <form acton="https://testpayments.nuve.com/merchant/subscrptonpage/regster" method="post"> <input type="hdden" name="TERMINALID" value="6491002"> <input type="hdden" name="MERCHANTREF" value="26352"> <input type="hdden" name="STOREDSUBSCRIPTIONREF" value="6523423"> <input type="hdden" name="SECUREACHACCOUNTMERCHANTREF" value="237498"> <input type="hdden" name="DATETIME" value="03-08-2009:17:32:18:329"> <input type="hdden" name="STARTDATE" value="04-08-2009"> <input type="hdden" name="ENDDATE" value="03-08-2010"> <input type="hdden" name="HASH" value="b9a034421808a80dc8f1a5657da80f95"> <input type="submt" value="Regster"> </form> </body> <html>

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:

Field Name

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.

7.2 XML Subscriptions Integration link

Stored Subscription and Subscriptions can be managed through XML Gateway.

7.2.1 Stored Subscription Creation Request link

The following is an example of a Stored Subscription Registration request for a terminal:

XML
<?xml verson="1.0" encodng="UTF-8"?> <ADDSTOREDSUBSCRIPTION> <MERCHANTREF>MR001</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>30-07-2009:15:26:38:027</DATETIME> <NAME>Anmal Lfe</NAME> <DESCRIPTION>Magazne membershp</DESCRIPTION> <PERIODTYPE>MONTHLY</PERIODTYPE> <LENGTH>12</LENGTH> <CURRENCY>EUR</CURRENCY> <RECURRINGAMOUNT>15.87</RECURRINGAMOUNT> <INITIALAMOUNT>10.99</INITIALAMOUNT> <TYPE>AUTOMATIC</TYPE> <ONUPDATE>CONTINUE</ONUPDATE> <ONDELETE>CANCEL</ONDELETE> <HASH>750f7c545a3d63ecaf3b48c149b95555</HASH> <CUSTOMFIELD NAME=”ACCOUNTID”></CUSTOMFIELD> <CUSTOMFIELD NAME=”EVENTID” /> </ADDSTOREDSUBSCRIPTION>

Example of a Stored Subscription Updating request:

XML
<?xml verson="1.0" encodng="UTF-8"?> <UPDATESTOREDSUBSCRIPTION> <MERCHANTREF>13231</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-07-2009:16:07:21:000</DATETIME> <NAME>Anmal Lfe</NAME> <DESCRIPTION>Magazne membershp</DESCRIPTION> <LENGTH>12</LENGTH> <CURRENCY>EUR</CURRENCY> <RECURRINGAMOUNT>15.99</RECURRINGAMOUNT> <INITIALAMOUNT>10.99</INITIALAMOUNT> <TYPE>AUTOMATIC</TYPE> <ONUPDATE>CONTINUE</ONUPDATE> <ONDELETE>CANCEL</ONDELETE> <HASH>5023bbb6726d1b5d2dcb7c77f11b94f</HASH> <CUSTOMFIELD NAME=”ACCOUNTID”></CUSTOMFIELD> <CUSTOMFIELD NAME=”EVENTID” /> </UPDATESTOREDSUBSCRIPTION>

Fields description:

Field Name

REQ

Register

REQ

Update

Description

MERCHANTREF

 Y Y

Unique merchant identifer  per terminal. Length is limited to

48 chars.

TERMINALID

 Y Y

A TerminalID provided by Nuvei.

DATETIME

 Y Y

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

 

Field Name

REQ

Register

REQ

Update

 Description

NAME

 Y Y

Display name for subscription

DESCRIPTION

 Y Y

Description explaining subscription

PERIODTYPE                                           

 Y N

Period  Type,  can  be:  WEEKLY,  FORTNIGHTLY,  MONTHLY, QUARTERLY, YEARLY. Only allowed for ADDSTOREDSUBSCRIPTION request.

LENGTH                                                    

 Y Y

 0 for non ending / multiplier of period. This does not take efect if (Subscription length * Period Type) >i  (End Date – Current Date).

CURRENCY                                              

 Y Y

Currency of subscription, this must either the base currency of the terminal or if supported, one of the confgured allowed currencies.

RECURRINGAMOUNT

 Y Y

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

INITIALAMOUNT

 Y Y

Initial (set-up) payment to be taken of card. Payment will not

be taken if it is 0.

TYPE                                                           

 Y Y

  MANUAL      /     AUTOMATIC      /     AUTOMATIC      (WITHOUT AMOUNTS).

 

ONUPDATE                                              

 Y Y

UPDATE/CONTINUE          (Update          name,          description, recurringprice,  setupprice,  subscriptionlength,  periodtype, type  for  all  subscriptions/Let  them  fnish  their  subscription prior to update).

ONDELETE                                               

 Y Y

CANCEL/CONTINUE   (Cancel   all   subscriptions   /   Continue subscriptions until cancelled manually or reach end date or length).

HASH

 Y Y

An SHA-512 HASH. See note 1 below.

CUSTOMFIELD

 N N

Use the “NAME” xml attribute to assign the name of the custom feld. See section 2.3 for more info. No value is required and any value sent will be ignored.

 

Notes:

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

 

TERMINALID:MERCHANTREF:DATETIME:TYPE:NAME:CURRENCY:RECURRINGAMOUNT: 

INITIALAMOUNT:LENGTH:secret

 If new stored subscription was successfully registered, response would be:

XML
<ADDSTOREDSUBSCRIPTIONRESPONSE> <MERCHANTREF>13231</MERCHANTREF> <DATETIME>30-07-2009:15:26:39:745</DATETIME> <HASH>d04c3bab519095ecb046ef91722e8df</HASH> </ADDSTOREDSUBSCRIPTIONRESPONSE>

Example of a successful stored subscription updating response:

<UPDATESTOREDSUBSCRIPTIONRESPONSE> <MERCHANTREF>13231</MERCHANTREF> <DATETIME>31-07-2009:16:07:21:329</DATETIME> <HASH>0af49616cad0fd1e19bc709de7d7c934</HASH> </UPDATESTOREDSUBSCRIPTIONRESPONSE>

 

The following felds will be returned in the response:

Field Name

Description
MERCHANTREF Original Merchant Reference sent in registration reques
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:secret

Errors handling

If stored subscription was not registered or updated, error code and error message will be returned:

XML
<ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>

Stored Subscription creation and updating error codes:

Error Code

 Description
E01 SYSTEM ERROR – TRY AGAIN
E03 OPERATION NOT ALLOWED
E06 INVALID TERMINALID
E07 METHOD NOT SUPPORTED
E07 INVALID MERCHANTREF
E08 INVALID DATETIME
 

 

Error Code

 Description

E13

 INVALID HASH

E20

 INVALID LENGTH

E21

 INVALID PERIOD TYPE
E22 INVALID NAME
E23 INVALID DESCRIPTION
E24 INVALID RECURRINGAMOUNT
E25 INVALID INITIALAMOUNT
E26 INVALID TYPE
E27 INVALID ONUPDATE
E28 INVALID ONDELETE
E29 INVALID TERMINAL CURRENCY

 

 

7.2.2 Stored Subscription Deletion Request link

Note that Stored 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.

To delete stored subscription following XML Gateway request should be send:

 

XML
<?xml verson="1.0" encodng="UTF8"?> <DELETESTOREDSUBSCRIPTION> <MERCHANTREF>13231</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-07-2009:20:49:34:798</DATETIME> <HASH>efc5a04b5a98be9bd59ec5383abb9161</HASH> </DELETESTOREDSUBSCRIPTION>

Fields description:

Field Name Required Description
MERCHANTREF Y Unique merchant identifer per terminal. Length is limited to 48
chars.
TERMINALID Y A TerminalID provided by Nuvei.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS.
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:DATETIME:secret

Example of a successful stored subscription deletion response:

 

XML
<DELETESTOREDSUBSCRIPTIONRESPONSE> <MERCHANTREF>13231</MERCHANTREF> <DATETIME>31-07-2009:20:49:35:381</DATETIME> <HASH>8a8f462278c730e9de5561d8f186d7dc</HASH> </DELETESTOREDSUBSCRIPTIONRESPONSE>

The following felds will be returned in the response:

Field Name Description
MERCHANTREF Original Merchant Refernce sent in registration request.
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:secret

Errors handling

If stored subscription was not registered or updated, error code and error message will be returned:

XML
<ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>

There is list of error codes and corresponding messages:

Error Code Description
E01 SYSTEM ERROR – TRY AGAIN
E03 OPERATION NOT ALLOWED
E06 INVALID TERMINALID
E07 METHOD NOT SUPPORTED
E08 INVALID MERCHANTREF
E09 INVALID DATETIME
E13 INVALID HASH

7.2.3 Subscription Creation Request link

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

XML
<?xml verson="1.0" encodng="UTF-8"?> <ADD_ACH_SUBSCRIPTION> <MERCHANTREF>Sub_CSV_09344573</MERCHANTREF> <TERMINALID>2366006</TERMINALID> <ACHREFERENCE>2967530284987420</ACHREFERENCE> or <SECUREACHACCOUNTMERCHANTREF></SECUREACHACCOUNTMERCHANTREF> <SEC_CODE>TEL</SEC_CODE> <DATETIME>06-03-2017:18:09:04:583</DATETIME> <RECURRINGAMOUNT>2.0</RECURRINGAMOUNT> <INITIALAMOUNT>13.0</INITIALAMOUNT> <STARTDATE>06-03-2017</STARTDATE> <ENDDATE>17-05-2020</ENDDATE> <HASH>05b0f69a72dd7b25883c7b8ed3918ae9</HASH> </ADD_ACH_SUBSCRIPTION>

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:

XML
<?xml verson="1.0" encodng="UTF-8"?> <ADD_ACH_SUBSCRIPTION> <MERCHANTREF>Sub_CSV_09344573</MERCHANTREF> <TERMINALID>2366006</TERMINALID> <ACHREFERENCE>2967530284987420</ACHREFERENCE> or <SECUREACHACCOUNTMERCHANTREF></SECUREACHACCOUNTMERCHANTREF> <SEC_CODE>TEL</SEC_CODE> <DATETIME>06-03-2017:18:09:04:583</DATETIME> <RECURRINGAMOUNT>2.0</RECURRINGAMOUNT> <INITIALAMOUNT>13.0</INITIALAMOUNT> <STARTDATE>06-03-2017</STARTDATE> <ENDDATE>17-05-2020</ENDDATE> <NEWSTOREDSUBSCRIPTIONINFO> <MERCHANTREF>Sub_CSV_09344573</MERCHANTREF> <NAME>name</NAME> <DESCRIPTION>descrpton test</DESCRIPTION> <PERIODTYPE>WEEKLY</PERIODTYPE> <LENGTH>12</LENGTH> <CURRENCY>USD</CURRENCY> <RECURRINGAMOUNT>3.0</RECURRINGAMOUNT> <INITIALAMOUNT>12.0</INITIALAMOUNT> <TYPE>AUTOMATIC</TYPE> <ONUPDATE>CONTINUE</ONUPDATE> <ONDELETE>CANCEL</ONDELETE> </NEWSTOREDSUBSCRIPTIONINFO> <HASH>05b0f69a72dd7b25883c7b8ed3918ae9</HASH> </ADD_ACH_SUBSCRIPTION>

Fields description:

Field Name Required Description
MERCHANTREF Y Unique merchant identifer per terminal. Length is limited to 48
chars.
TERMINALID Y A TerminalID provided by Nuvei.
STOREDSUBSCRIPTIONREF N 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

2. STOREDSUBSCRIPTIONREF should be omitted if it is not set.

 

NEWSTOREDSUBSCRIPTIONINFO felds description:

Field Name Required Description
MERCHANTREF Y Unique merchant identifer per terminal. Length is limited to 48
chars.
NAME Y Display name for subscription.
DESCRIPTION Y Description explaining subscription.
PERIODTYPE Y Period Type, can be: WEEKLY, FORTNIGHTLY, MONTHLY,
QUARTERLY or YEARLY.
LENGTH Y 0 for non ending multiplier of period. This does not take efect if
(Subscription length * Period Type) >i (End Date – Current Date).
CURRENCY Y Currency of subscription, this must either the base currency of the
terminal or if supported, one of the confgured allowed currencies.
RECURRINGAMOUNT N Cost of each payment (should not be sent if TYPE is “MANUAL”).
INITIALAMOUNT Y Initial (set-up) payment to be taken of card. Payment will not be
taken if it is 0.
TYPE Y MANUAL or AUTOMATIC.
ONUPDATE Y UPDATE or CONTINUE (Update name, description, recurringprice,
setupprice, subscriptionlength, periodtype, type for all
subscriptions/Let them fnish their subscription prior to update).
ONDELETE Y CANCEL/CONTINUE (Cancel all subscriptions / Continue
subscriptions until cancelled manually or reach end date or length).

 

Example of a successful subscription creation response:

 

XML
<ADDSUBSCRIPTIONRESPONSE> <MERCHANTREF>MR02-02</MERCHANTREF> <DATETIME>30-07-2009:15:34:24:305</DATETIME> <HASH>8bb39be67a1f05bf73fe334e12037257</HASH> </ADDSUBSCRIPTIONRESPONSE>

The following felds will be returned in the response:

Field Name Description
MERCHANTREF Original Merchant Reference sent in registration request.
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:secret

 

Errors handling

If new subscription was not registered, error code and error message will be returned:

<ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>

7.2.4 Subscription Updating Request link

The following is an example of a Subscription Updating request:

XML
<?xml verson="1.0" encodng="UTF-8"?> <UPDATE_ACH_SUBSCRIPTION> <MERCHANTREF>Sub_CSV_09344573</MERCHANTREF> <TERMINALID>2366006</TERMINALID> <ACHREFERENCE>2967530284987420</ACHREFERENCE> or <SECUREACHACCOUNTMERCHANTREF></SECUREACHACCOUNTMERCHANTREF> <SEC_CODE>CCD</SEC_CODE> <DATETIME>06-03-2017:18:38:02:154</DATETIME> <NAME>NameUpdated_CSV_11082143</NAME> <LENGTH>10</LENGTH> <SKIPPERIODCOUNT>1</SKIPPERIODCOUNT> <RECURRINGAMOUNT>5.0</RECURRINGAMOUNT> <STARTDATE>06-03-2017</STARTDATE> <ENDDATE>06-11-2017</ENDDATE> <HASH>3cfc892047e5a1154e0f4c2e7cb29980</HASH> </UPDATE_ACH_SUBSCRIPTION>

Fields description:

Field Name Required Description
MERCHANTREF Y Merchant Ref of subscription which should be updated.
TERMINALID Y A TerminalID provided by Nuvei.
ACHREFERENCE N System-Generated ACH Reference (Secure ACH).(Only one of
SECUREACHACCOUNTMERCHANTREF or ACHREFERENCE must be
present)
SECUREACHACCOUNTMERCH
ANTREF		 N Merchant Reference of a Secure ACH which will be used to do
recurring payments.(Only one of SECURECARDMERCHANTREF or
ACHREFERENCE must be present)
SEC_CODE Y See section 2.4 above.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS.
NAME N Subscription Name.
DESCRIPTION N Subscription Description.
LENGTH N Subscription Length.
RECURRINGAMOUNT N New Recurring Amount.
STARTDATE N Subscription Start Date.
ENDDATE N Subscription End Date, if it is not set subscription will continue until
manually canceled or lenght reached (if it is set).
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:DATETIME:STARTDATE:secret
or
TERMINALID:MERCHANTREF:ACHREFERENCE :DATETIME:STARTDATE:secret

 

Example of a successful subscription updating response:

XML
<UPDATE_ACH_SUBSCRIPTION_RESPONSE> <MERCHANTREF>Sub_CSV_09344573</MERCHANTREF> <DATETIME>06-03-2017:17:38:02:399</DATETIME> <HASH>e0f3de3996b57b1ac57b6cf92b5de046</HASH> </UPDATE_ACH_SUBSCRIPTION_RESPONSE>

The following felds will be returned in the response:

Field Name Description
MERCHANTREF Original Merchant Reference sent in registration request
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:secret

 

Errors handling

If subscription was not updated, error code and error message will be returned:

 

XML
<ERROR>i <ERRORCODE>iE08</ERRORCODE>i <ERRORSTRING>iINVALID MERCHANTREF</ERRORSTRING>i </ERROR>i

7.2.5 Subscription Deletion Request link

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.

The following is an example of a Subscription Deletion request:

XML
<?xml verson="1.0" encodng="UTF8"?> <DELETESUBSCRIPTIONACH> <MERCHANTREF>MR002</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-07-2009:11:03:42:328</DATETIME> <HASH>53b6917aac8eb179e8b80f754c4afd5c</HASH> </DELETESUBSCRIPTIONACH>

Fields description:

Field Name Required Description
MERCHANTREF Y Merchant Ref of subscription which should be deleted.
TERMINALID Y A TerminalID provided by Nuvei.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS.
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:DATETIME:secret

Example of a successful subscription deletion response:

 

XML
<DELETESUBSCRIPTIONRESPONSE> <MERCHANTREF>MR002</MERCHANTREF> <DATETIME>30-07-2009:15:34:24:305</DATETIME> <HASH>8bb39be67a1f05bf73fe334e12037257</HASH> </DELETESUBSCRIPTIONRESPONSE>

The following felds will be returned in the response:

Field Name Description
MERCHANTREF Original Merchant Reference sent in registration request.
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:secret

 

Errors handling

If subscription was not deleted, error code and error message will be returned:

XML
<ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>

7.2.6 Subscription Cancellation Request link

Cancelling a subscription is exactly the same as deleting a subscription.

The following is an example of a Subscription Cancellation request:

XML
<?xml verson="1.0" encodng="UTF8"?> <CANCELSUBSCRIPTIONACH> <MERCHANTREF>MR002</MERCHANTREF> <TERMINALID>6491002</TERMINALID> <DATETIME>31-07-2009:11:03:42:328</DATETIME> <HASH>53b6917aac8eb179e8b80f754c4afd5c</HASH> </CANCELSUBSCRIPTIONACH>

Fields description:

Field Name Required Description
MERCHANTREF Y Merchant Ref of subscription which should be deleted.
TERMINALID Y A TerminalID provided by Nuvei.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS.
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:DATETIME:secret

Example of a successful subscription cancellation response:

XML
<CANCELSUBSCRIPTIONRESPONSE> <MERCHANTREF>MR002</MERCHANTREF> <DATETIME>30-07-2009:15:34:24:305</DATETIME> <HASH>8bb39be67a1f05bf73fe334e12037257</HASH> </CANCELSUBSCRIPTIONRESPONSE>

The following felds will be returned in the response:

Field Name Description
MERCHANTREF Original Merchant Reference sent in registration request.
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:secret

 

Errors handling

If subscription was not cancelled, error code and error message will be returned:

 

XML
<ERROR> <ERRORCODE>E08</ERRORCODE> <ERRORSTRING>INVALID MERCHANTREF</ERRORSTRING> </ERROR>

7.2.7 Subscription Payment Request link

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:

XML
<?xml verson="1.0" encodng="UTF-8"?> <ACH_SUBSCRIPTION_PAYMENT> <ORDERID>CSV_95790073</ORDERID> <TERMINALID>2366006</TERMINALID> <AMOUNT>3.94</AMOUNT> <SUBSCRIPTIONREF>mRef102</SUBSCRIPTIONREF> <SEC_CODE>WEB</SEC_CODE> <DATETIME>07-03-2017:18:09:50:137</DATETIME> <HASH>e088efde331594ec2d881479735368c5</HASH> </ACH_SUBSCRIPTION_PAYMENT>

Fields description:

Field Name Required Description
SUBSCRIPTIONREF Y Merchant reference of a subscription being paid.
ORDERID Y A unique identifer for the order created by the merchant. (Max 12
Characters).
TERMINALID Y A TerminalID provided by Nuvei. NB – Please contact Nuvei to be
issued with a test terminal ID.
AMOUNT Y The amount of the transaction as a 2 digit decimal or an Integer value
for JPY amounts.
SEC_CODE Y See section 2.4 above.
DATETIME Y Format: DD-MM-YYYY:HH:MM:SS:SSS
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:ORDERID:SUBSCRIPTIONREF:AMOUNT:DATETIME:secret

 

Example of a successful subscription payment response:

 

XML
<ACH_SUBSCRIPTION_PAYMENT_RESPONSE> <UNIQUEREF>JIZDZ59H1D</UNIQUEREF> <RESPONSECODE>E</RESPONSECODE> <RESPONSETEXT>ACCEPTED</RESPONSETEXT> <APPROVALCODE>Success</APPROVALCODE> <DATETIME>2017-03-07T17:09:54</DATETIME> <HASH>50909e43de3161f884db589c66deaee3</HASH> </ACH_SUBSCRIPTION_PAYMENT_RESPONSE>

The following felds are returned in the response:

Field Name Description
APPROVALCODE Six digit AuthCode.
UNIQUEREF Generated reference that should be stored for tracking and remote XML
refunding.
RESPONSECODE A or D or R(Approved or Declined or Referral).
RESPONSETEXT The text of the authorization.
DATETIME The time of the transaction created by the bank. Format: DD-MMYYYY:
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:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:secret

2. For multi-currency Terminal IDs (see section 3.2 above) this should be:

TERMINALID:ORDERID:UNIQUEREF:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:
RESPONSETEXT:secret

n.b. The response UNIQUEREF is to be used here

Errors handling

If subscription payment was not accepted, error message will be returned:

XML
<ERROR> <ERRORCODE>E41</ERRORCODE> <ERRORSTRING>Invald HASH feld</ERRORSTRING> </ERROR>

7.3 Subscription Notifcations link

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:

 

TERMINALID:MERCHANTREF:NOTIFICATIONTYPE:DATETIME:ORDERID: AMOUNT:
RESPONSECODE:RESPONSETEXT:secret

Need Help?

How can we help you today?  Our team is standing by and just a click away.

Knowledge Base Contact Support