Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
developer:api_specification:xml_subscription_features [2019/07/16 13:15]
thiago123 [Request Body Fields]
developer:api_specification:xml_subscription_features [2019/07/16 13:15] (current)
thiago123 [Notes and Details About the Request]
Line 1: Line 1:
 +====== XML Subscription Features ======
  
 +~~TOC~~
 +
 +\\
 +The subscription features, presented in this page, allow your integration to manage recurring payments in the Gateway Platform.
 +
 +The %CompanyName Subscription 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 and “XML Payment Request” or through the %SelfCare System. Another difference with this method is that you can modify the amount of the payment.
 +
 +<WRAP center important 100%>
 +This feature requires that you use the Secure Card feature as well. A subscription uses a Secure Card to perform the payments. So without Secure Cards, you can't use a subscription.
 +</​WRAP>​
 +\\
 +
 +The Subscription solution has two big 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**:​ Those 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 overruled 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, represents 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 | %URLXMLPayments |
 +| XML XSD descriptor | %URLGateway |
 +
 +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 ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| MERCHANTREF | Y | Unique merchant identifier per terminal. Length is limited to 48 chars. |
 +| TERMINALID | Y | A Terminal ID provided by %CompanyName. |
 +| 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 **[[developer:​api_specification:​special_fields_and_parameters|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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details About the Request ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​DATETIME:​TYPE:​NAME:​PERIODTYPE:​CURRENCY:​RECURRINGAMOUNT:​INITIALAMOUNT:​LENGTH:​SECRET
 +</​WRAP>​
 +
 +\\
 +
 +**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.
 +
 +<code xml>
 +<?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>​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +==== Response Body Fields ====
 +
 +The response body fields will be:
 +
 +<​searchtable>​
 +^ **FIELD** ^ **DESCRIPTION** ^
 +| MERCHANTREF | Same as the one informed 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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details on the Response ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​DATETIME:​SECRET
 +</​WRAP>​
 +\\
 +
 +**ND002 - Error Handling**
 +
 +If there is an error processing the transaction,​ the error string is returned in an XML message with the simple tags:
 +
 +<code xml>
 +<​ERROR>​
 +    <​ERRORSTRING>​This is the error generated!</​ERRORSTRING>​
 +</​ERROR>​
 +</​code>​
 +\\
 +
 +**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.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​ADDSTOREDSUBSCRIPTIONRESPONSE>​
 + <​MERCHANTREF>​13231</​MERCHANTREF>​
 + <​DATETIME>​30-07-2009:​15:​26:​39:​745</​DATETIME>​
 + <​HASH>​d04c3bab519095ecb046eff91722e8df</​HASH>​
 +</​ADDSTOREDSUBSCRIPTIONRESPONSE>​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +===== 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 ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| MERCHANTREF ​     | Y | Unique merchant identifier per terminal. Length is limited to 48 chars. ​                                                                                                                |
 +| TERMINALID ​      | Y | A Terminal ID provided by %CompanyName. ​                                                                                                                                                |
 +| 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 **[[developer:​api_specification:​special_fields_and_parameters|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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details About the Request ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​DATETIME:​TYPE:​NAME:​CURRENCY:​RECURRINGAMOUNT:​INITIALAMOUNT:​LENGTH:​SECRET
 +</​WRAP>​
 +\\
 +
 +**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.
 +
 +<code xml>
 +<?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>​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +==== Response Body Fields ====
 +
 +The response body fields will be:
 +
 +<​searchtable>​
 +^ **FIELD** ^ **DESCRIPTION** ^
 +| MERCHANTREF | Same as the one informed 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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details on the Response ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​DATETIME:​SECRET
 +</​WRAP>​
 +\\
 +
 +**ND002 - Error Handling**
 +
 +If there is an error processing the transaction,​ the error string is returned in an XML message with the simple tags:
 +
 +<code xml>
 +<​ERROR>​
 +    <​ERRORSTRING>​This is the error generated!</​ERRORSTRING>​
 +</​ERROR>​
 +</​code>​
 +\\
 +
 +**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.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​UPDATESTOREDSUBSCRIPTIONRESPONSE>​
 + <​MERCHANTREF>​13231</​MERCHANTREF>​
 + <​DATETIME>​31-07-2009:​16:​07:​21:​329</​DATETIME>​
 + <​HASH>​0af49616cad0fd1e19bc709de7d7c934</​HASH>​
 +</​UPDATESTOREDSUBSCRIPTIONRESPONSE>​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +===== 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 ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| MERCHANTREF ​     | Y | Unique merchant identifier of an existing Stored Subscription,​ informed on registration'​s request. Length is limited to 48 chars. |
 +| TERMINALID ​      | Y | A Terminal ID provided by %CompanyName. |
 +| 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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details About the Request ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​DATETIME:​SECRET
 +</​WRAP>​
 +\\
 +
 +**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.
 +
 +<code xml>
 +<?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>​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +==== Response Body Fields ====
 +
 +The response body fields will be:
 +
 +<​searchtable>​
 +^ **FIELD** ^ **DESCRIPTION** ^
 +| MERCHANTREF | Same as the one informed 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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details on the Response ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​DATETIME:​SECRET
 +</​WRAP>​
 +\\
 +
 +**ND002 - Error Handling**
 +
 +If there is an error processing the transaction,​ the error string is returned in an XML message with the simple tags:
 +
 +<code xml>
 +<​ERROR>​
 +    <​ERRORSTRING>​This is the error generated!</​ERRORSTRING>​
 +</​ERROR>​
 +</​code>​
 +\\
 +
 +**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.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​DELETESTOREDSUBSCRIPTIONRESPONSE>​
 + <​MERCHANTREF>​13231</​MERCHANTREF>​
 + <​DATETIME>​31-07-2009:​20:​49:​35:​381</​DATETIME>​
 + <​HASH>​8a8f462278c730e9de5561d8f186d7dc</​HASH>​
 +</​DELETESTOREDSUBSCRIPTIONRESPONSE>​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +===== 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 ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| MERCHANTREF ​     | Y | Unique merchant identifier for the new subscription. Length is limited to 48 chars. |
 +| TERMINALID ​      | Y | A Terminal ID provided by %CompanyName. |
 +| STOREDSUBSCRIPTIONREF ​     | N | Stored Subscription Merchant Reference. \\ Only STOREDSUBSCRIPTIONREF or NEWSTOREDSUBSCRIPTIONINFO must be informed. |
 +| 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 informed. |
 +| 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 informed. |
 +| CARDREFERENCE ​             | N | System-Generated Secure Card reference.\\ Only SECURECARDMERCHANTREF or CARDREFERENCE must be informed. |
 +| 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"​. |
 +| 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. |
 +| 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 **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]**. Limited to 30 custom fields in this request. |
 +|LEVEL_2_DATA | N |Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See **ND004 - Level 2 Data Validation**. |
 +|LEVEL_3_DATA | N |Component of the request that can be added in case the Level 3 Data feature is in use for the Terminal processing the Payment. See **ND005 - Level 3 Data Validation**. | 
 +
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details About the Request ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +If using the SECURECARDMERCHANTREF field to create the subscription:​
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​STOREDSUBSCRIPTIONREF:​SECURECARDMERCHANTREF:​DATETIME:​STARTDATE:​SECRET
 +</​WRAP>​
 +
 +If using the CARDREFERENCE field to create the subscription:​
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​STOREDSUBSCRIPTIONREF:​CARDREFERENCE:​DATETIME:​STARTDATE:​SECRET
 +</​WRAP>​
 +\\
 +
 +**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). ​                                                                 |
 +
 +\\
 +
 +**ND004 - Level 2 Data Validation**
 +
 +This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the "Allow Enhanced Data (Level II and Level III)" enabled with the "​Transaction Data Level" option set as "Level II" on the Processing Terminal “Features” section.
 +
 +To provide a transaction with LEVEL 2, your request needs to add the LEVEL_2_DATA component and its fields, as described below.
 +
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| CUSTOMER_REF_NUMBER ​ | N | Text type with max length of 48 characters. This number is defined by the cardmember. It is entered by the merchant at the point of sale. |
 +| TAX_AMOUNT | N | Integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions. |
 +| SHIPPING_ADDRESS | N | A subcomponent with all the data related to the shipping address of a purchase. |
 +| FULL_NAME ​ | N | Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. |
 +| ADDRESS1 ​ | N | Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. |
 +| ADDRESS2 | N | Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Always optional regardless compulsory setting. |
 +| CITY  | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. |
 +| REGION ​ | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. |
 +| POSTCODE ​ | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters. |
 +| COUNTRY ​ | N | Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code. |
 +
 +\\
 +
 +Quick example:
 +
 +<code xml>
 +<​LEVEL_2_DATA>​
 +    <​CUSTOMER_REF_NUMBER>​SDGK-JSAAS-0235.00002314</​CUSTOMER_REF_NUMBER>​
 +    <​TAX_AMOUNT>​151.27</​TAX_AMOUNT>​
 +    <​SHIPPING_ADDRESS>​
 + <​FULL_NAME>​JOHN SMITH AND ASSOCIATES</​FULL_NAME>​
 + <​ADDRESS1>​Unit 001, Street X</​ADDRESS1>​
 + <​ADDRESS2>​Block "​A",​ Neighborhood "​A"</​ADDRESS2>​
 + <​CITY>​City "​Y"</​CITY>​
 + <​REGION>​Region 1</​REGION>​
 + <​POSTCODE>​A00B0001</​POSTCODE>​
 + <​COUNTRY>​Country "​Z"</​COUNTRY>​
 + </​SHIPPING_ADDRESS>​
 +</​LEVEL_2_DATA>​
 +</​code>​
 +
 +\\
 +
 +**ND005 - Level 3 Data Validation**
 +
 +This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the "Allow Enhanced Data (Level II and Level III)" enabled with the "​Transaction Data Level" option set as "Level III" on the Processing Terminal “Features” section.
 +
 +To provide a transaction with LEVEL 3, your request needs to add the LEVEL_2_DATA (described before) and the LEVEL_3_DATA components and their fields. The LEVEL_3_DATA component fields are described below.
 +
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| SUMMARY | N | Subcomponent of Level 3. Agregates the sums of different values within the transaction. |
 +| TOTAL_DISCOUNT_AMOUNT | N | Subfield of SUMMARY. Represents the total value assigned as discount to the sale. That considers the resulting sum from all items' discunts rates (unit price x quantity x discount rate) and any other additional discount applied after that. \\ Decimal value, allowing max of 13 digits with min value of 0. |
 +| TOTAL_FREIGHT_AMOUNT | N | Subfield of SUMMARY. Represents the freight amount applied to the sale. \\ Decimal value, allowing max of 13 digits with min value of 0. |
 +| TOTAL_DUTY_AMOUNT | N | Subfield of SUMMARY. Represents the duty amount applied to the sale. \\ Decimal value, allowing max of 13 digits with min value of 0. |
 +| LINE_ITEMS | N | Subcomponent of Level 3. List of all items in which the sale is broken down. |
 +| LINE_ITEM | N | Subfield of LINE_ITEMS. Holds all the details of a sale's item. You can add as much as necessary to express the breaking down of your sale. |
 +| COMMODITY_CODE | N | Subfield of LINE_ITEM. Item's commodidy code, defined for trade tariff. Widely used by corporate purchasing organizations to segment and manage their total spend across diverse product lines. Defined at government or commercial aggrements level. Consult your Acquirer for more details. |
 +| PRODUCT_CODE | N | Subfield of LINE_ITEM. This is the merchant’s identifier for the product, also known as Universal Product code (UPC). |
 +| DESCRIPTION | N | Subfield of LINE_ITEM. This is the merchant’s description for the product. |
 +| QUANTITY | N | Subfield of LINE_ITEM. Quantity of the specific item for the sale. |
 +| UNIT_OF_MEASURE | N | Subfield of LINE_ITEM. Measure unit used for this specific item type to sell it in parts, units or sets. |
 +| UNIT_PRICE | N | Subfield of LINE_ITEM. Unit price applied for that specific type of item and measure unit, within the sale. |
 +| DISCOUNT_RATE | N | Subfield of LINE_ITEM. A % of discount applied to the item total (quantity x unit price) before taxes. |
 +| TAX_RATE | N | Subfield of LINE_ITEM. A % of tax applied to the item total (quantity x unit price) after discounts. |
 +| TOTAL_AMOUNT | N | Subfield of LINE_ITEM. Final item value based on total (quantity x unit price), after discount and tax applied. |
 +
 +\\
 +
 +Quick example:
 +
 +<code xml>
 +<​LEVEL_2_DATA>​...</​LEVEL_2_DATA>​
 +<​LEVEL_3_DATA>​
 +    <​SUMMARY>​
 +        <​TOTAL_DISCOUNT_AMOUNT>​61.30</​TOTAL_DISCOUNT_AMOUNT>​
 +        <​TOTAL_FREIGHT_AMOUNT>​3.50</​TOTAL_FREIGHT_AMOUNT>​
 +        <​TOTAL_DUTY_AMOUNT>​11.50</​TOTAL_DUTY_AMOUNT>​
 +    </​SUMMARY>​
 +    <​LINE_ITEMS> ​
 +        <!-- As many as necessary -->
 +        <​LINE_ITEM>​
 +            <​COMMODITY_CODE>​PDX001</​COMMODITY_CODE>​
 +            <​PRODUCT_CODE>​DSV1303.090.00001</​PRODUCT_CODE>​
 +            <​DESCRIPTION>​General services</​DESCRIPTION>​
 +            <​QUANTITY>​10</​QUANTITY>​
 +            <​UNIT_OF_MEASURE>​Hour</​UNIT_OF_MEASURE>​
 +            <​UNIT_PRICE>​105.50</​UNIT_PRICE>​
 +            <​DISCOUNT_RATE>​5.00</​DISCOUNT_RATE>​
 +            <​TAX_RATE>​12.50</​TAX_RATE>​
 +            <​TOTAL_AMOUNT>​1127.53</​TOTAL_AMOUNT>​
 +        </​LINE_ITEM>​
 +        <​LINE_ITEM>​
 +            <​COMMODITY_CODE>​PDX002</​COMMODITY_CODE>​
 +            <​PRODUCT_CODE>​DSV1302.090.00001</​PRODUCT_CODE>​
 +            <​DESCRIPTION>​General services</​DESCRIPTION>​
 +            <​QUANTITY>​2</​QUANTITY>​
 +            <​UNIT_OF_MEASURE>​Hour</​UNIT_OF_MEASURE>​
 +            <​UNIT_PRICE>​85.50</​UNIT_PRICE>​
 +            <​DISCOUNT_RATE>​5.00</​DISCOUNT_RATE>​
 +            <​TAX_RATE>​16.00</​TAX_RATE>​
 +            <​TOTAL_AMOUNT>​188.44</​TOTAL_AMOUNT>​
 +        </​LINE_ITEM>​
 +    </​LINE_ITEMS>​
 +</​LEVEL_3_DATA>​
 +</​code>​
 +
 +<WRAP info round 100%>
 +**DON'​T FORGET**
 +
 +If you are using LEVEL_3_DATA component, also add to your request the LEVEL_2_DATA 2 component to attempt a fully qualification for enhanced data.
 +
 +</​WRAP>​
 +
 +\\
 +==== Examples for a Request ====
 +
 +  * **Scenario**:​ Simple request to create a subscription.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?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>​
 +</​code>​
 +\\
 +
 +  * **Scenario**:​ Request to create a subscription,​ creating a stored subscription at the same time.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?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>​
 +</​code>​
 +\\
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +==== Response Body Fields ====
 +
 +The response body fields will be:
 +
 +<​searchtable>​
 +^ **FIELD** ^ **DESCRIPTION** ^
 +| MERCHANTREF | Same as the one informed 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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details on the Response ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​DATETIME:​SECRET
 +</​WRAP>​
 +\\
 +
 +**ND002 - Error Handling**
 +
 +If there is an error processing the transaction,​ the error string is returned in an XML message with the simple tags:
 +
 +<code xml>
 +<​ERROR>​
 +    <​ERRORSTRING>​This is the error generated!</​ERRORSTRING>​
 +</​ERROR>​
 +</​code>​
 +\\
 +
 +**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.
 +
 +<code xml>
 +<?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>​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +===== 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 ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| MERCHANTREF ​     | Y | Unique merchant identifier for the subscription to be updated. Length is limited to 48 chars. |
 +| TERMINALID ​      | Y | A Terminal ID provided by %CompanyName. |
 +| 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 informed. |
 +| CARDREFERENCE ​             | N | System-Generated Secure Card reference.\\ Only SECURECARDMERCHANTREF or CARDREFERENCE must be informed. |
 +| 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"​. |
 +| 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. |
 +| 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 **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]**. Limited to 30 custom fields in this request. |
 +|LEVEL_2_DATA | N |Component of the request that can be added in case the Level II Data feature is in use for the Terminal processing the Payment. See **ND003 - Level 2 Data Validation**. |
 +|LEVEL_3_DATA | N |Component of the request that can be added in case the Level 3 Data feature is in use for the Terminal processing the Payment. See **ND004 - Level 3 Data Validation**. | 
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details About the Request ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +If you are using the SECURECARDMERCHANTREF:​
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​SECURECARDMERCHANTREF:​DATETIME:​STARTDATE:​SECRET
 +</​WRAP>​
 +
 +If you are using the CARDREFERENCE:​
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​CARDREFERENCE:​DATETIME:​STARTDATE:​SECRET
 +</​WRAP>​
 +
 +\\
 +
 +**ND002 - Data Encoding for Requests**
 +
 +All data sent to us should be correctly encoded using **UTF-8** as the character encoding.
 +
 +\\
 +
 +**ND003 - Level 2 Data Validation**
 +
 +This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the "Allow Enhanced Data (Level II and Level III)" enabled with the "​Transaction Data Level" option set as "Level II" on the Processing Terminal “Features” section.
 +
 +To provide a transaction with LEVEL 2, your request needs to add the LEVEL_2_DATA component and its fields, as described below.
 +
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| CUSTOMER_REF_NUMBER ​ | N | Text type with max length of 48 characters. This number is defined by the cardmember. It is entered by the merchant at the point of sale. |
 +| TAX_AMOUNT | N | Integer type, with max length of 13 numbers. A value of zero is required in order to indicate tax exempt transactions. |
 +| SHIPPING_ADDRESS | N | A subcomponent with all the data related to the shipping address of a purchase. |
 +| FULL_NAME ​ | N | Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. |
 +| ADDRESS1 ​ | N | Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. |
 +| ADDRESS2 | N | Subfield of SHIPPING_ADDRESS. Value is text type, with max length of 50 characters. Always optional regardless compulsory setting. |
 +| CITY  | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. |
 +| REGION ​ | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 128 characters. |
 +| POSTCODE ​ | N | Subfield of SHIPPING_ADDRESS. Value is text type, between 1 and 50 characters. |
 +| COUNTRY ​ | N | Subfield of SHIPPING_ADDRESS. Value is text type, with 2 characters. ISO ALPHA-2 Country Code. |
 +
 +\\
 +
 +Quick example:
 +
 +<code xml>
 +<​LEVEL_2_DATA>​
 +    <​CUSTOMER_REF_NUMBER>​SDGK-JSAAS-0235.00002314</​CUSTOMER_REF_NUMBER>​
 +    <​TAX_AMOUNT>​151.27</​TAX_AMOUNT>​
 +    <​SHIPPING_ADDRESS>​
 + <​FULL_NAME>​JOHN SMITH AND ASSOCIATES</​FULL_NAME>​
 + <​ADDRESS1>​Unit 001, Street X</​ADDRESS1>​
 + <​ADDRESS2>​Block "​A",​ Neighborhood "​A"</​ADDRESS2>​
 + <​CITY>​City "​Y"</​CITY>​
 + <​REGION>​Region 1</​REGION>​
 + <​POSTCODE>​A00B0001</​POSTCODE>​
 + <​COUNTRY>​Country "​Z"</​COUNTRY>​
 + </​SHIPPING_ADDRESS>​
 +</​LEVEL_2_DATA>​
 +</​code>​
 +
 +\\
 +
 +**ND004 - Level 3 Data Validation**
 +
 +This field is associated with the Transaction Enhanced Data feature, and to be used it is necessary to have the "Allow Enhanced Data (Level II and Level III)" enabled with the "​Transaction Data Level" option set as "Level III" on the Processing Terminal “Features” section.
 +
 +To provide a transaction with LEVEL 3, your request needs to add the LEVEL_2_DATA (described before) and the LEVEL_3_DATA components and their fields. The LEVEL_3_DATA component fields are described below.
 +
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| SUMMARY | N | Subcomponent of Level 3. Agregates the sums of different values within the transaction. |
 +| TOTAL_DISCOUNT_AMOUNT | N | Subfield of SUMMARY. Represents the total value assigned as discount to the sale. That considers the resulting sum from all items' discunts rates (unit price x quantity x discount rate) and any other additional discount applied after that. \\ Decimal value, allowing max of 13 digits with min value of 0. |
 +| TOTAL_FREIGHT_AMOUNT | N | Subfield of SUMMARY. Represents the freight amount applied to the sale. \\ Decimal value, allowing max of 13 digits with min value of 0. |
 +| TOTAL_DUTY_AMOUNT | N | Subfield of SUMMARY. Represents the duty amount applied to the sale. \\ Decimal value, allowing max of 13 digits with min value of 0. |
 +| LINE_ITEMS | N | Subcomponent of Level 3. List of all items in which the sale is broken down. |
 +| LINE_ITEM | N | Subfield of LINE_ITEMS. Holds all the details of a sale's item. You can add as much as necessary to express the breaking down of your sale. |
 +| COMMODITY_CODE | N | Subfield of LINE_ITEM. Item's commodidy code, defined for trade tariff. Widely used by corporate purchasing organizations to segment and manage their total spend across diverse product lines. Defined at government or commercial aggrements level. Consult your Acquirer for more details. |
 +| PRODUCT_CODE | N | Subfield of LINE_ITEM. This is the merchant’s identifier for the product, also known as Universal Product code (UPC). |
 +| DESCRIPTION | N | Subfield of LINE_ITEM. This is the merchant’s description for the product. |
 +| QUANTITY | N | Subfield of LINE_ITEM. Quantity of the specific item for the sale. |
 +| UNIT_OF_MEASURE | N | Subfield of LINE_ITEM. Measure unit used for this specific item type to sell it in parts, units or sets. |
 +| UNIT_PRICE | N | Subfield of LINE_ITEM. Unit price applied for that specific type of item and measure unit, within the sale. |
 +| DISCOUNT_RATE | N | Subfield of LINE_ITEM. A % of discount applied to the item total (quantity x unit price) before taxes. |
 +| TAX_RATE | N | Subfield of LINE_ITEM. A % of tax applied to the item total (quantity x unit price) after discounts. |
 +| TOTAL_AMOUNT | N | Subfield of LINE_ITEM. Final item value based on total (quantity x unit price), after discount and tax applied. |
 +
 +\\
 +
 +Quick example:
 +
 +<code xml>
 +<​LEVEL_2_DATA>​...</​LEVEL_2_DATA>​
 +<​LEVEL_3_DATA>​
 +    <​SUMMARY>​
 +        <​TOTAL_DISCOUNT_AMOUNT>​61.30</​TOTAL_DISCOUNT_AMOUNT>​
 +        <​TOTAL_FREIGHT_AMOUNT>​3.50</​TOTAL_FREIGHT_AMOUNT>​
 +        <​TOTAL_DUTY_AMOUNT>​11.50</​TOTAL_DUTY_AMOUNT>​
 +    </​SUMMARY>​
 +    <​LINE_ITEMS> ​
 +        <!-- As many as necessary -->
 +        <​LINE_ITEM>​
 +            <​COMMODITY_CODE>​PDX001</​COMMODITY_CODE>​
 +            <​PRODUCT_CODE>​DSV1303.090.00001</​PRODUCT_CODE>​
 +            <​DESCRIPTION>​General services</​DESCRIPTION>​
 +            <​QUANTITY>​10</​QUANTITY>​
 +            <​UNIT_OF_MEASURE>​Hour</​UNIT_OF_MEASURE>​
 +            <​UNIT_PRICE>​105.50</​UNIT_PRICE>​
 +            <​DISCOUNT_RATE>​5.00</​DISCOUNT_RATE>​
 +            <​TAX_RATE>​12.50</​TAX_RATE>​
 +            <​TOTAL_AMOUNT>​1127.53</​TOTAL_AMOUNT>​
 +        </​LINE_ITEM>​
 +        <​LINE_ITEM>​
 +            <​COMMODITY_CODE>​PDX002</​COMMODITY_CODE>​
 +            <​PRODUCT_CODE>​DSV1302.090.00001</​PRODUCT_CODE>​
 +            <​DESCRIPTION>​General services</​DESCRIPTION>​
 +            <​QUANTITY>​2</​QUANTITY>​
 +            <​UNIT_OF_MEASURE>​Hour</​UNIT_OF_MEASURE>​
 +            <​UNIT_PRICE>​85.50</​UNIT_PRICE>​
 +            <​DISCOUNT_RATE>​5.00</​DISCOUNT_RATE>​
 +            <​TAX_RATE>​16.00</​TAX_RATE>​
 +            <​TOTAL_AMOUNT>​188.44</​TOTAL_AMOUNT>​
 +        </​LINE_ITEM>​
 +    </​LINE_ITEMS>​
 +</​LEVEL_3_DATA>​
 +</​code>​
 +
 +<WRAP info round 100%>
 +**DON'​T FORGET**
 +
 +If you are using LEVEL_3_DATA component, also add to your request the LEVEL_2_DATA 2 component to attempt a fully qualification for enhanced data.
 +
 +</​WRAP>​
 +
 +\\
 +
 +==== Examples for a Request ====
 +
 +  * **Scenario**:​ Simple request to update valid subscription.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?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> ​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +==== Response Body Fields ====
 +
 +The response body fields will be:
 +
 +<​searchtable>​
 +^ **FIELD** ^ **DESCRIPTION** ^
 +| MERCHANTREF | Same as the one informed 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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details on the Response ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​DATETIME:​SECRET
 +</​WRAP>​
 +\\
 +
 +**ND002 - Error Handling**
 +
 +If there is an error processing the transaction,​ the error string is returned in an XML message with the simple tags:
 +
 +<code xml>
 +<​ERROR>​
 +    <​ERRORSTRING>​This is the error generated!</​ERRORSTRING>​
 +</​ERROR>​
 +</​code>​
 +\\
 +
 +**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 OR SECURECARDACHACCOUNTMERCHANTREF |
 +| 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.
 +
 +<code xml>
 +<?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>​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +===== Subscription Delete =====
 +
 +This feature allows you to delete an existing subscription.
 +
 +  * **Main Request body Tag**: <​DELETESUBSCRIPTION> ​
 +  * **Main Response body Tag**: <​DELETESUBSCRIPTIONRESPONSE> ​
 +  ​
 +==== Request Body Fields ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| MERCHANTREF | Y | Unique merchant identifier for the subscription to be deleted. Length is limited to 48 chars. |
 +| TERMINALID | Y | A Terminal ID provided by %CompanyName. |
 +| 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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details About the Request ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​DATETIME:​SECRET
 +</​WRAP>​
 +\\
 +
 +**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.
 +
 +<code xml>
 +<?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>​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +==== Response Body Fields ====
 +
 +The response body fields will be:
 +
 +<​searchtable>​
 +^ **FIELD** ^ **DESCRIPTION** ^
 +| MERCHANTREF | Same as the one informed 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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details on the Response ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​DATETIME:​SECRET
 +</​WRAP>​
 +\\
 +
 +**ND002 - Error Handling**
 +
 +If there is an error processing the transaction,​ the error string is returned in an XML message with the simple tags:
 +
 +<code xml>
 +<​ERROR>​
 +    <​ERRORSTRING>​This is the error generated!</​ERRORSTRING>​
 +</​ERROR>​
 +</​code>​
 +
 +\\
 +
 +**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.
 +
 +<code xml>
 +<?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>​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +===== 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 ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| ORDERID ​                    | Y | A unique identifier for the order created by the merchant. Maximum of 24 characters. |
 +| TERMINALID ​                 | Y | A TerminalID provided by %CompanyName. |
 +| 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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details About the Request ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +<WRAP center box 100%>
 +TERMINALID:​ORDERID:​SUBSCRIPTIONREF:​AMOUNT:​DATETIME:​SECRET
 +</​WRAP>​
 +\\
 +
 +**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 **[[developer:​api_specification:​xml_payment_features#​edcc_exchange_rate| eDCC Exchange Rate ]]** feature.
 +
 +\\
 +==== Examples for a Request ====
 +
 +  * **Scenario**:​ Simple subscription payment request with FOREIGNCURRENCYINFORMATION.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?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>​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +==== Response Body Fields ====
 +
 +The response body fields will be:
 +
 +<​searchtable>​
 +^ **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 **[[merchant:​existing_merchant:​other_information:​transaction_responses|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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details on the Response ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +<WRAP center box 100%>
 +TERMINALID:​UNIQUEREF:​AMOUNT:​DATETIME:​RESPONSECODE:​RESPONSETEXT:​SECRET
 +</​WRAP>​
 +\\
 +
 +**ND002 - Error Handling**
 +
 +If there is an error processing the transaction,​ the error string is returned in an XML message with the simple tags:
 +
 +<code xml>
 +<​ERROR>​
 +    <​ERRORSTRING>​This is the error generated!</​ERRORSTRING>​
 +</​ERROR>​
 +</​code>​
 +\\
 +
 +==== Examples for the Response ====
 +
 +  * **Scenario**:​ .
 +  * **Terminal**:​ .
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?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>​
 +</​code>​
 +
 +<WRAP center important 100%>
 +**REMEMBER** to change the Terminal Id and Terminal Secret for valid values.
 +Verify the **[[developer:​integration_docs|Integration Docs]]** for viable examples or contact our support team.
 +</​WRAP>​
 +
 +\\
 +
 +===== Subscriptions Notification =====
 +
 +The subscription notification is a feature which allows the Payment Gateway to notify the Merchant about events associated to its subscriptions.
 +
 +This is only possible when the Subscription Notification URL is informed at the Terminal configuration - you can see it at the Terminal Setup page of the %SelfCare System. ​
 +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 NOTIFICATIOTYPE),​ 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:
 +
 +<​searchtable>​
 +^ **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. |
 +| UNIQUEREF | Generated reference for the transaction resulting from the subscription processing. Not returned for stored subscription actions. |
 +| 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. |
 +</​searchtable>​
 +\\
 +
 +==== Notes and Details About the Request ====
 +
 +**ND001 - Hash Formation**
 +
 +The general rule to build HASH field is given at the **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]** page, under the **[[developer:​api_specification:​special_fields_and_parameters#​the_hash_parameter|Special Fields and Parameters]]** section. For this specific feature, you should use the following formats:
 +
 +When the NOTIFICATIONTYPE is SUBSCRIPTIONSETUPPAYMENT or SUBSCRIPTIONRECURRINGPAYMENT:​
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​NOTIFICATIONTYPE:​DATETIME:​ORDERID:​AMOUNT:​RESPONSECODE:​RESPONSETEXT:​SECRET
 +</​WRAP>​
 +
 +Any other case:
 +
 +<WRAP center box 100%>
 +TERMINALID:​MERCHANTREF:​NOTIFICATIONTYPE:​DATETIME:​RESPONSECODE:​RESPONSETEXT:​SECRET
 +
 +</​WRAP>​
 + 
 +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.
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International