- 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.
- 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.
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:
|
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 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 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:
Example of a successful stored subscription updating response:
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:
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:
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:
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:
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 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 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:
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:
7.2.4 Subscription Updating Request link
The following is an example of a Subscription Updating request:
<?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:
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:
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:
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:
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:
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:
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:
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:
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 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:
<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:
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:
Possible values for stored subscriptions are:
|
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