XML Subscription

The Gateway's Subscription feature is a versatile solution which can be used in two main ways:

1. Automatic Subscription: 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 Subscription: With this solution, recurring payments are set up in our system just as they are for automatic payments. The main difference is that our system does not actually process payments automatically. Instead, when a payment is pending, the merchant should initiate the payment, either via an “XML Payment Request” or through the SelfCare System (Merchant Portal). Another difference with this method is that you can modify the amount of the payment.

This feature requires that you also use the Secure Card feature. Subscriptions use Secure Cards (tokens) to perform payments.

The Subscription solution has two main components:

Stored Subscriptions: They act not as subscription, but as templates for multiple subscriptions registered under them. They define the period (weekly / monthly / quarterly / annually), the number of those periods (if it's a fixed number), setup price, recurring price, etc. They are intended to represent a product, for example. This way you can define “models” which can be applied to many clients with the same settings.

Subscriptions: These are the actual subscriptions. Every subscription set up has to be under a Stored Subscription. However some of the settings of the stored subscription can be overridden by the Subscription itself, as you will see below. Subscriptions are intended to represent a specific order of a product represented by the stored subscription that it's under. Also, they represent the “charging” configuration for a specific client.

The following resources are the same for all the requests and responses you find in this page:

TYPE	URL
Request URL	https://testpayments.nuvei.com/merchant/xmlpayment
XML XSD descriptor	https://testpayments.nuvei.com/merchant/gateway.xsd

Use the Request URL and the Request Body Fields to perform a request for this feature, then prepare your integration to receive the response, as defined by the Response Body Fields.

Stored Subscription Registration

This feature allows you to perform the registration of a stored subscription.

Main Request body Tag: <ADDSTOREDSUBSCRIPTION>
Main Response body Tag: <ADDSTOREDSUBSCRIPTIONRESPONSE>

Request Body Fields

Filter:

FIELD	REQUIRED	DESCRIPTION
MERCHANTREF	Y	Unique merchant identifier per terminal. Length is limited to 48 chars.
TERMINALID	Y	The merchant's terminal ID.
NAME	Y	Display name for subscription.
DESCRIPTION	Y	Description explaining subscription.
PERIODTYPE	Y	Value can be: WEEKLY, FORTNIGHTLY, MONTHLY, QUARTERLY or YEARLY.
LENGTH	Y	0 for non ending/ multiplier of period. This does not take effect if (Subscription length * Period Type) > (End Date - Current Date).
CURRENCY	Y	Currency of subscription, this must either the base currency of the terminal or if supported, one of the configured allowed currencies.
RECURRINGAMOUNT	Y	Cost of each payment. Should only be sent if the TYPE is AUTOMATIC, otherwise an error is going to be generated.
INITIALAMOUNT	Y	Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0. Should only be sent if the TYPE is AUTOMATIC or MANUAL, otherwise an error is going to be generated.
TYPE	Y	MANUAL / AUTOMATIC / AUTOMATIC (WITHOUT AMOUNTS).
ONUPDATE	Y	UPDATE/CONTINUE (Update name, description, recurringprice, setupprice, subscriptionlength, periodtype, type for all subscriptions/ let them finish their subscription prior to update).
ONDELETE	Y	CANCEL/CONTINUE (Cancel all subscriptions/Continue subscription until cancelled manually or reach end date or length).
CUSTOMFIELD'N'	N	Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. Their values are going to be stored and used by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding Special Fields and Parameters. Limited to 30 custom fields in this request.
DATETIME	Y	Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	Y	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

TERMINALID:MERCHANTREF:DATETIME:TYPE:NAME:PERIODTYPE:CURRENCY:RECURRINGAMOUNT:INITIALAMOUNT:LENGTH:SECRET

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

Examples for a Request

Scenario: Simple request to create stored subscription.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<ADDSTOREDSUBSCRIPTION>
	<MERCHANTREF>MR001</MERCHANTREF>
	<TERMINALID>6491002</TERMINALID>
	<DATETIME>30-07-2009:15:26:38:027</DATETIME>
	<NAME>Animal Life</NAME>
	<DESCRIPTION>Magazine membership</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>
</ADDSTOREDSUBSCRIPTION>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Response Body Fields

The response body fields will be:

Filter:

FIELD	DESCRIPTION
MERCHANTREF	Same as the one provided on request.
DATETIME	Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details on the Response

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

TERMINALID:MERCHANTREF:DATETIME:SECRET

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

ND003 - Response Codes - Errors

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
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

Examples for the Response

Scenario: Response to the simple request.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<ADDSTOREDSUBSCRIPTIONRESPONSE>
	<MERCHANTREF>13231</MERCHANTREF>
	<DATETIME>30-07-2009:15:26:39:745</DATETIME>
	<HASH>d04c3bab519095ecb046eff91722e8df</HASH>
</ADDSTOREDSUBSCRIPTIONRESPONSE>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Stored Subscription Update

This feature allows you to perform the update of a valid stored subscription.

Main Request body Tag: <UPDATESTOREDSUBSCRIPTION>
Main Response body Tag: <UPDATESTOREDSUBSCRIPTIONRESPONSE>

Request Body Fields

Filter:

FIELD	REQUIRED	DESCRIPTION
MERCHANTREF	Y	Unique merchant identifier per terminal. Length is limited to 48 chars.
TERMINALID	Y	The merchant's terminal ID.
NAME	Y	Display name for subscription.
DESCRIPTION	Y	Description explaining subscription.
LENGTH	Y	0 for non ending/ multiplier of period. This does not take effect if (Subscription length * Period Type) > (End Date - Current Date).
CURRENCY	Y	Currency of subscription, this must either the base currency of the terminal or if supported, one of the configured allowed currencies.
RECURRINGAMOUNT	Y	Cost of each payment. Should only be sent if the TYPE is AUTOMATIC, otherwise an error is going to be generated.
INITIALAMOUNT	Y	Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0. Should only be sent if the TYPE is AUTOMATIC or MANUAL, otherwise an error is going to be generated.
TYPE	Y	MANUAL / AUTOMATIC / AUTOMATIC (WITHOUT AMOUNTS).
ONUPDATE	Y	UPDATE/CONTINUE (Update name, description, recurringprice, setupprice, subscriptionlength, periodtype, type for all subscriptions/ let them finish their subscription prior to update)
ONDELETE	Y	CANCEL/CONTINUE (Cancel all subscriptions/Continue subscription until cancelled manually or reach end date or length).
CUSTOMFIELD'N'	N	Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. Their values are going to be stored and used by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding Special Fields and Parameters. Limited to 30 custom fields in this request.
DATETIME	Y	Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	Y	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

TERMINALID:MERCHANTREF:DATETIME:TYPE:NAME:CURRENCY:RECURRINGAMOUNT:INITIALAMOUNT:LENGTH:SECRET

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

Examples for a Request

Scenario: Simple request to update stored subscription.
Merchant referece: 13231.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<UPDATESTOREDSUBSCRIPTION>
	<MERCHANTREF>13231</MERCHANTREF>
	<TERMINALID>6491002</TERMINALID>
	<DATETIME>31-07-2009:16:07:21:000</DATETIME>
	<NAME>Animal Life</NAME>
	<DESCRIPTION>Magazine membership</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>5023bbb6726d1b5d2dcb7c77fb11b94f</HASH>
</UPDATESTOREDSUBSCRIPTION>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Response Body Fields

The response body fields will be:

Filter:

FIELD	DESCRIPTION
MERCHANTREF	Same as the one provided on request.
DATETIME	Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details on the Response

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

TERMINALID:MERCHANTREF:DATETIME:SECRET

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

ND003 - Response Codes - Errors

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
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

Examples for the Response

Scenario: Response to the simple request.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<UPDATESTOREDSUBSCRIPTIONRESPONSE>
	<MERCHANTREF>13231</MERCHANTREF>
	<DATETIME>31-07-2009:16:07:21:329</DATETIME>
	<HASH>0af49616cad0fd1e19bc709de7d7c934</HASH>
</UPDATESTOREDSUBSCRIPTIONRESPONSE>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Stored Subscription Delete

This feature allows you to delete a valid stored subscription.

Main Request body Tag: <DELETESTOREDSUBSCRIPTION>
Main Response body Tag: <DELETESTOREDSUBSCRIPTIONRESPONSE>

Request Body Fields

Filter:

FIELD	REQUIRED	DESCRIPTION
MERCHANTREF	Y	Unique merchant identifier of an existing Stored Subscription, provided on registration's request. Length is limited to 48 chars.
TERMINALID	Y	The merchant's terminal ID.
DATETIME	Y	Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	Y	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

TERMINALID:MERCHANTREF:DATETIME:SECRET

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

Examples for a Request

Scenario: Simple request to delete existing stored subscription.
Terminal: 6491002.
Merchant reference: 13231.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<DELETESTOREDSUBSCRIPTION>
	<MERCHANTREF>13231</MERCHANTREF>
	<TERMINALID>6491002</TERMINALID>
	<DATETIME>31-07-2009:20:49:34:798</DATETIME>
	<HASH>efc5a04b5a98be9bd59ec5383abb9161</HASH>
</DELETESTOREDSUBSCRIPTION>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Response Body Fields

The response body fields will be:

Filter:

FIELD	DESCRIPTION
MERCHANTREF	Same as the one provided on request.
DATETIME	Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details on the Response

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

TERMINALID:MERCHANTREF:DATETIME:SECRET

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

ND003 - Response Codes - Errors

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

Examples for the Response

Scenario: Response to the simple request.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<DELETESTOREDSUBSCRIPTIONRESPONSE>
	<MERCHANTREF>13231</MERCHANTREF>
	<DATETIME>31-07-2009:20:49:35:381</DATETIME>
	<HASH>8a8f462278c730e9de5561d8f186d7dc</HASH>
</DELETESTOREDSUBSCRIPTIONRESPONSE>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Subscription Registration

This feature allows you to perform the registration of a subscription. Additionally to that, you can also, while registering the subscription, register a stored subscription, by just adding its fields to the request.

Main Request body Tag: <ADDSUBSCRIPTION>
Main Response body Tag: <ADDSUBSCRIPTIONRESPONSE>

Request Body Fields

Filter:

FIELD	REQUIRED	DESCRIPTION
MERCHANTREF	Y	Unique merchant identifier for the new subscription. Length is limited to 48 chars.
TERMINALID	Y	The merchant's terminal ID.
STOREDSUBSCRIPTIONREF	N	Stored Subscription Merchant Reference. Only STOREDSUBSCRIPTIONREF or NEWSTOREDSUBSCRIPTIONINFO must be provided.
NEWSTOREDSUBSCRIPTIONINFO	N	It is allowed only if STOREDSUBSCRIPTIONREF is not set. This tag and all it's children should be set if Stored Subscription on which new subscription being added should be based doesn't exist yet and should be created. Take a look at ND003 - Stored Subscription Creation with Subcription for details. Only STOREDSUBSCRIPTIONREF or NEWSTOREDSUBSCRIPTIONINFO must be provided.
SECURECARDMERCHANTREF	N	Merchant Reference of a Secure Card which will be used to do set-up and recurring payments. Only SECURECARDMERCHANTREF or CARDREFERENCE must be provided.
CARDREFERENCE	N	System-Generated Secure Card reference. Only SECURECARDMERCHANTREF or CARDREFERENCE must be provided.
RECURRINGAMOUNT	N	Cost of each payment. Should only be sent if stored subscription type is “Automatic (without amounts)” and new stored subscription is NOT being created.
INTIALAMOUNT	N	Initial (set-up) payment to be taken off card. payment will not be taken if it is 0. should only be sent if stored subscription type is “Automatic (without amounts)” and new subscription is NOT being created.
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 length reached (if it is set). Format: DD-MM-YYYY.
EDCCDECISION	N	This field is supported by a eDCC-enabled terminals only and will be ignored if terminal doesn't support eDCC. Can be “Y” or “N”.
CUSTOMFIELD'N'	N	Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. Their values are going to be stored and used by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding Special Fields and Parameters. Limited to 30 custom fields in this request.
DATETIME	Y	Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
NOTIFICATIONLANGUAGE	N	Defines the language which is going to be used to send the customer's notification/ receipt. Acceptable values are 'EN' and 'FR' (case sensitive).
HASH	Y	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

If using the SECURECARDMERCHANTREF field to create the subscription:

TERMINALID:MERCHANTREF:STOREDSUBSCRIPTIONREF:SECURECARDMERCHANTREF:DATETIME:STARTDATE:SECRET

If using the CARDREFERENCE field to create the subscription:

TERMINALID:MERCHANTREF:STOREDSUBSCRIPTIONREF:CARDREFERENCE:DATETIME:STARTDATE:SECRET

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

ND003 - Stored Subscription Creation with Subcription

The following fields represent the nested elements of NEWSTOREDSUBSCRIPTIONINFO, to be used qhen creating the stored subscription at the same time as the subscription.

FIELD	REQUIRED	DESCRIPTION
MERCHANTREF	Y	Unique merchant identifier per terminal. Length is limited to 48 chars.
NAME	Y	Display name for subscription.
DESCRIPTION	Y	Description explaining subscription.
PERIODTYPE	Y	Value can be: WEEKLY, FORTNIGHTLY, MONTHLY, QUARTERLY or YEARLY.
LENGTH	Y	0 for non ending/ multiplier of period. This does not take effect if (Subscription length * Period Type) > (End Date - Current Date).
CURRENCY	Y	Currency of subscription, this must either the base currency of the terminal or if supported, one of the configured allowed currencies.
RECURRINGAMOUNT	Y	Cost of each payment (will be ignored if manual).
INITIALAMOUNT	Y	Initial (set-up) payment to be taken off card. Payment will not be taken if it is 0.
TYPE	Y	MANUAL / AUTOMATIC / AUTOMATIC (WITHOUT AMOUNTS).
ONUPDATE	Y	UPDATE/CONTINUE (Update name, description, recurringprice, setupprice, subscriptionlength, periodtype, type for all subscriptions/ let them finish their subscription prior to update)
ONDELETE	Y	CANCEL/CONTINUE (Cancel all subscriptions/Continue subscription until cancelled manually or reach end date or length).

Examples for a Request

Scenario: Simple request to create a subscription.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<ADDSUBSCRIPTION>
	<MERCHANTREF>MR01-02</MERCHANTREF>
	<TERMINALID>6491002</TERMINALID>
	<STOREDSUBSCRIPTIONREF>MR01</STOREDSUBSCRIPTIONREF>
	<SECURECARDMERCHANTREF>7126</SECURECARDMERCHANTREF>
	<DATETIME>30-07-2009:15:34:23:671</DATETIME>
	<STARTDATE>01-08-2009</STARTDATE>
	<ENDDATE>31-07-2010</ENDDATE>
	<EDCCDECISION>Y</EDCCDECISION>
        <HASH>99a8addc5cac111c21a9aa48aae3c363</HASH>
	<CUSTOMFIELD NAME=”ACCOUNTID”>9238746529</CUSTOMFIELD>
	<CUSTOMFIELD NAME=”EVENTID”>44</CUSTOMFIELD>
</ADDSUBSCRIPTION>

Scenario: Request to create a subscription, creating a stored subscription at the same time.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<ADDSUBSCRIPTION>
	<MERCHANTREF>MR02-02</MERCHANTREF>
	<TERMINALID>6491002</TERMINALID>
	<SECURECARDMERCHANTREF>7126</SECURECARDMERCHANTREF>
	<DATETIME>30-07-2009:15:34:23:671</DATETIME>
	<STARTDATE>01-08-2009</STARTDATE>
	<ENDDATE>31-07-2010</ENDDATE>
	<EDCCDECISION>Y</EDCCDECISION>
	<NEWSTOREDSUBSCRIPTIONINFO>
		<MERCHANTREF>MR001</MERCHANTREF>
		<NAME>Animal Life</NAME>
		<DESCRIPTION>Magazine membership</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>
	</NEWSTOREDSUBSCRIPTIONINFO>
	<HASH>8515ccc5605651c12ab0645f79eb0271</HASH>
	<CUSTOMFIELD NAME=”ACCOUNTID”>9238746529</CUSTOMFIELD>
	<CUSTOMFIELD NAME=”EVENTID”>44</CUSTOMFIELD>
</ADDSUBSCRIPTION>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Response Body Fields

The response body fields will be:

Filter:

FIELD	DESCRIPTION
MERCHANTREF	Same as the one provided on request.
DATETIME	Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details on the Response

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

TERMINALID:MERCHANTREF:DATETIME:SECRET

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

ND003 - Response Codes - Errors

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
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
E30	INVALID STORED SUBSCRIPTION REF
E31	INVALID STORED SUBSCRIPTION MERCHANT REF
E32	INVALID SECURE CARDS MERCHANT REF
E33	INVALID STARTDATE
E34	INVALID ENDDATE
E35	INVALID EDCCDCECISION
E36	SETUP PAYMENT PROCESSING ERROR
E37	INVALID SUBSCRIPTIONRECURRINGAMOUNT
E38	INVALID SUBSCRIPTIONINITIALAMOUNT
E39	SECURE CARD NOT VALIDATED
E48	INVALID SECURE CARD REFERENCE
E49	SECURECARDMERCHANTREF AND CARDREFERENCE ARE ABSENT (ONLY ONE OF THEM IS REQUIRED)
E50	SECURECARDMERCHANTREF AND CARDREFERENCE ARE BOTH PRESENT (ONLY ONE OF THEM IS REQUIRED)

Examples for the Response

Scenario: Response to the simple request.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<ADDSUBSCRIPTIONRESPONSE>
	<MERCHANTREF>MR02-02</MERCHANTREF>
	<DATETIME>30-07-2009:15:34:24:305</DATETIME>
	<HASH>8bb39be67a1f05bf73fe334e12037257</HASH>
</ADDSUBSCRIPTIONRESPONSE>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Subscription Update

This feature allows you to perform the update of an existing and valid subscription.

Main Request body Tag: <UPDATESUBSCRIPTION>
Main Response body Tag: <UPDATESUBSCRIPTIONRESPONSE>

Request Body Fields

Filter:

FIELD	REQUIRED	DESCRIPTION
MERCHANTREF	Y	Unique merchant identifier for the subscription to be updated. Length is limited to 48 chars.
TERMINALID	Y	The merchant's terminal ID.
SECURECARDMERCHANTREF	N	Merchant Reference of a Secure Card which will be used to do set-up and recurring payments. Only SECURECARDMERCHANTREF or CARDREFERENCE must be provided.
CARDREFERENCE	N	System-Generated Secure Card reference. Only SECURECARDMERCHANTREF or CARDREFERENCE must be provided.
NAME	Y	Display name for subscription.
DESCRIPTION	Y	Description explaining subscription.
LENGTH	Y	0 for non ending/ multiplier of period. This does not take effect if (Subscription length * Period Type) > (End Date - Current Date).
RECURRINGAMOUNT	N	Cost of each payment. Should only be sent if stored subscription type is “AUTOMATIC (WITHOUT AMOUNTS)”.
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 length reached (if it is set). Format: DD-MM-YYYY.
EDCCDECISION	N	This field is supported by a eDCC-enabled terminals only and will be ignored if terminal doesn't support eDCC. Can be “Y” or “N”.
CUSTOMFIELD'N'	N	Any of the available Custom Fields for the Terminal. Their values are going to be stored and can be used by the Payment Gateway later on. Their values are going to be stored and used by the Payment Gateway for the requests sent to the Receipt URL and the Validation URL. To understand more visit the section regarding Special Fields and Parameters. Limited to 30 custom fields in this request.
DATETIME	Y	Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
NOTIFICATIONLANGUAGE	N	Defines the language which is going to be used to send the customer's notification/ receipt. Acceptable values are 'EN' and 'FR' (case sensitive).
HASH	Y	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

If you are using the SECURECARDMERCHANTREF:

TERMINALID:MERCHANTREF:SECURECARDMERCHANTREF:DATETIME:STARTDATE:SECRET

If you are using the CARDREFERENCE:

TERMINALID:MERCHANTREF:CARDREFERENCE:DATETIME:STARTDATE:SECRET

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

Examples for a Request

Scenario: Simple request to update valid subscription.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<UPDATESUBSCRIPTION>
       <MERCHANTREF>MR001</MERCHANTREF>
       <TERMINALID>6491002</TERMINALID>
       <SECURECARDMERCHANTREF>8328</SECURECARDMERCHANTREF>
       <DATETIME>30-07-2009:09:59:38:921</DATETIME>
       <NAME>Animal Life</NAME>
       <DESCRIPTION>Magazine membership</DESCRIPTION>
       <PERIODTYPE>MONTHLY</PERIODTYPE>
       <LENGTH>12</LENGTH>
       <RECURRINGAMOUNT>15.87</RECURRINGAMOUNT>
       <STARTDATE>23-08-2009</STARTDATE>
       <ENDDATE>22-08-2010</ENDDATE>
       <EDCCDECISION>Y</EDCCDECISION>
       <HASH>53b6917aac8eb179e8b80f754c4afd5c</HASH>
</UPDATESUBSCRIPTION>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Response Body Fields

The response body fields will be:

Filter:

FIELD	DESCRIPTION
MERCHANTREF	Same as the one provided on request.
DATETIME	Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details on the Response

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

TERMINALID:MERCHANTREF:DATETIME:SECRET

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

ND003 - Response Codes - Errors

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
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
E30	INVALID STORED SUBSCRIPTION REF
E31	INVALID STORED SUBSCRIPTION MERCHANT REF
E32	INVALID SECURE CARDS MERCHANT REF
E33	INVALID STARTDATE
E34	INVALID ENDDATE
E35	INVALID EDCCDCECISION
E36	SETUP PAYMENT PROCESSING ERROR
E37	INVALID SUBSCRIPTIONRECURRINGAMOUNT
E38	INVALID SUBSCRIPTIONINITIALAMOUNT
E39	SECURE CARD NOT VALIDATED
E41	PASS ONLY ONE OF CARDREFERENCE OR SECURECARDMERCHANTREF
E48	INVALID SECURE CARD REFERENCE
E49	SECURECARDMERCHANTREF AND CARDREFERENCE ARE ABSENT (ONLY ONE OF THEM IS REQUIRED)
E50	SECURECARDMERCHANTREF AND CARDREFERENCE ARE BOTH PRESENT (ONLY ONE OF THEM IS REQUIRED)

Examples for the Response

Scenario: Response to the simple request.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<UPDATESUBSCRIPTIONRESPONSE>
      <MERCHANTREF>MR02-02</MERCHANTREF>
      <DATETIME>30-07-2009:15:34:24:305</DATETIME>
      <HASH>8bb39be67a1f05bf73fe334e12037257</HASH>
</UPDATESUBSCRIPTIONRESPONSE>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Subscription Delete

This feature allows you to delete an existing subscription.

Main Request body Tag: <DELETESUBSCRIPTION>
Main Response body Tag: <DELETESUBSCRIPTIONRESPONSE>

Request Body Fields

Filter:

FIELD	REQUIRED	DESCRIPTION
MERCHANTREF	Y	Unique merchant identifier for the subscription to be deleted. Length is limited to 48 chars.
TERMINALID	Y	The merchant's terminal ID.
DATETIME	Y	Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	Y	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

TERMINALID:MERCHANTREF:DATETIME:SECRET

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

Examples for a Request

Scenario: Simple request to delete a subscription.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<DELETESUBSCRIPTION>
	<MERCHANTREF>MR002</MERCHANTREF>
	<TERMINALID>6491002</TERMINALID>
	<DATETIME>31-07-2009:11:03:42:328</DATETIME>
	<HASH>53b6917aac8eb179e8b80f754c4afd5c</HASH>
</DELETESUBSCRIPTION>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Response Body Fields

The response body fields will be:

Filter:

FIELD	DESCRIPTION
MERCHANTREF	Same as the one provided on request.
DATETIME	Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details on the Response

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

TERMINALID:MERCHANTREF:DATETIME:SECRET

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

ND003 - Response Codes - Errors

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

Examples for the Response

Scenario: Response to the simple request.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<DELETESUBSCRIPTIONRESPONSE>
	<MERCHANTREF>MR02-02</MERCHANTREF>
	<DATETIME>30-07-2009:15:34:24:305</DATETIME>
	<HASH>8bb39be67a1f05bf73fe334e12037257</HASH>
</DELETESUBSCRIPTIONRESPONSE>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Subscription Payment

Manual recurring payment can be done using this subscription feature. Also, when an automatic subscription has any problems and could not process a payment automatically, because of card details expiration or other issue, this missing payment can also be executed in the same way as a manual subscription payment, after the problems with the payment details is solved.

This feature allows you to perform a payment of a subscription.

Main Request body Tag: <SUBSCRIPTIONPAYMENT>
Main Response body Tag: <SUBSCRIPTIONPAYMENTRESPONSE>

Request Body Fields

Filter:

FIELD	REQUIRED	DESCRIPTION
ORDERID	Y	A unique identifier for the order created by the merchant. Maximum of 24 characters.
TERMINALID	Y	The merchant's terminal ID.
AMOUNT	Y	The amount of the transaction as a 2 digit decimal or an Integer value for JPY amounts.
SUBSCRIPTIONREF	Y	Merchant reference of a subscription being paid.
DESCRIPTION	N	Transaction Description.
FOREIGNCURRENCYINFORMATION	N	Tag contains Dynamic Currency Conversion information. It has to be present in the eDCC enabled transactions. See the next section, ND003 - Using eDCC, for more details on this field.
EMAIL	N	Cardholder e-mail address.
DATETIME	Y	Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	Y	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

TERMINALID:ORDERID:SUBSCRIPTIONREF:AMOUNT:DATETIME:SECRET

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

ND003 - Using eDCC

All eDCC enabled XML requests must include FOREIGNCURRENCYINFORMATION tag and it nested tags.

PARAMETER NAME	REQUIRED	DESCRIPTION
CARDCURRENCY	Y	Card's currency code.
CARDAMOUNT	Y	Amount which is supposed to be charged in the home currency.
CONVERSIONRATE	Y	Value received in the Conversion Rate request should be there. Processing bank (EuroConex) will decline transaction if wrong rate will be there.

Those fields can be obtained by using the eDCC Exchange Rate feature.

Examples for a Request

Scenario: Simple subscription payment request with FOREIGNCURRENCYINFORMATION.
Terminal: 6491002.
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<SUBSCRIPTIONPAYMENT>
	<ORDERID>8362</ORDERID>
	<TERMINALID>6491002</TERMINALID>
	<AMOUNT>87.78</AMOUNT>
	<SUBSCRIPTIONREF>311</SUBSCRIPTIONREF>
	<FOREIGNCURRENCYINFORMATION>
		<CARDCURRENCY>JPY</CARDCURRENCY>
		<CARDAMOUNT>10638</CARDAMOUNT>
		<CONVERSIONRATE>121.186190</CONVERSIONRATE>
	</FOREIGNCURRENCYINFORMATION>
	<EMAIL>cardholder_email@worldnettps.com</EMAIL>
	<DATETIME>31-07-2009:14:09:59:121</DATETIME>
	<HASH>53b6917aac8eb179e8b80f754c4afd5c</HASH>
	<CUSTOMFIELD NAME=”ACCOUNTID”>132453462</CUSTOMFIELD>
	<CUSTOMFIELD NAME=”EVENTID”>FG00001</CUSTOMFIELD>
</SUBSCRIPTIONPAYMENT>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Response Body Fields

The response body fields will be:

Filter:

FIELD	DESCRIPTION
RESPONSECODE	A: (APPROVED/ AUTHORIZED/ ACCEPTED, respectively). E: (ACCEPTED for later processing, but result currently unknown - specifically for China Union Pay). D: (DECLINED). R: (REFERRED, also considered as PICKUP). C: (PICKUP, also known as Referral A or Referral B). For more details, visit at Transaction Responses.
RESPONSETEXT	The text of the authorization.
APPROVALCODE	A 6 digit AuthCode.
DATETIME	Response date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details on the Response

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

TERMINALID:UNIQUEREF:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET

ND002 - Error Handling

If there is an error processing the transaction, the error string is returned in an XML message with the simple tags:

<ERROR>
    <ERRORSTRING>This is the error generated!</ERRORSTRING>
</ERROR>

Examples for the Response

Scenario: .
Terminal: .
Terminal Secret: x4n35c32RT.

<?xml version="1.0" encoding="UTF-8"?>
<SUBSCRIPTIONPAYMENTRESPONSE>
	<RESPONSECODE>A</RESPONSECODE>
	<RESPONSETEXT>APPROVAL</RESPONSETEXT>
	<APPROVALCODE>406243</APPROVALCODE>
	<DATETIME>31-07-2009:14:10:03:834</DATETIME>
	<HASH>6dd32c4b61f180dd791310f9c07d76a1</HASH>
</SUBSCRIPTIONPAYMENTRESPONSE>

REMEMBER to replace the TERMINALID and Terminal Secret with valid values.

Subscriptions Notification

The subscription notification is a feature which allows the Payment Gateway to notify the Merchant about events associated with subscriptions.

This is only possible when the Subscription Notification URL is set - you can configure it using the Terminal Setup page of the SelfCare System (Merchant Portal). If the URL is in place, a POST notification will be sent to this URL each time an automated activity happens on any active subscriptions. Note that manual changes applied to subscriptions via the SelfCare System will not generate these notifications.

Request Body Fields

The data sent to the Subscription Notification URL contains all the normal subscription response fields (depending on the action performed, as NOTIFICATIONTYPE), plus the following extra fields below. So, to know how each notification body works, you need to consider the same body of each feature of the Subscription solution, then add the following fields:

Filter:

FIELD	DESCRIPTION
NOTIFICATIONTYPE	Possible values for subscriptions: SUBSCRIPTIONCREATION. SUBSCRIPTIONUPDATING . SUBSCRIPTIONDELETION . SUBSCRIPTIONSETUPPAYMENT . SUBSCRIPTIONRECURRINGPAYMENT . Possible values for stored subscriptions: STOREDSUBSCRIPTIONCREATION . STOREDSUBSCRIPTIONUPDATING . STOREDSUBSCRIPTIONDELETION.
ORDERID	The Order ID that the system assigned to the Subscription payment. Only sent for SUBSCRIPTIONSETUPPAYMENT and SUBSCRIPTIONRECURRINGPAYMENT. Maximum of 24 characters.
TERMINALID	The Terminal ID that the subscription is set up on.
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.
DATETIME	Request date and time. Format: DD-MM-YYYY:HH:MM:SS:SSS.
HASH	A HASH code formed by part of the request fields. The formation rule is given at the ND001 - Hash Formation, in the next section.

Notes and Details About the Request

ND001 - Hash Formation

The general rule to build HASH field is given at the Special Fields and Parameters page, under the Hash Parameter section. For this specific feature, you should use the following formats:

When the NOTIFICATIONTYPE is SUBSCRIPTIONSETUPPAYMENT or SUBSCRIPTIONRECURRINGPAYMENT:

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

Any other case:

TERMINALID:MERCHANTREF:NOTIFICATIONTYPE:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET

Note that for Stored Subscriptions, RESPONSECODE and RESPONSETEXT, will always be blank.

ND002 - Data Encoding for Requests

All data sent to us should be correctly encoded using UTF-8 as the character encoding.

Response Body Fields

The successful response expected to this request is a body containing a “OK” with a HTTP Status of 200. Anything else will be considered an unsuccessful attempt of notification by the Payment Gateway.