Differences

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

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
developer:api_specification:xml_terminal_features [2019/02/12 11:44]
thiago123 [Get Terminal Configuration] release - level 3 features
developer:api_specification:xml_terminal_features [2022/10/07 14:38] (current)
Line 1: Line 1:
 +====== XML Terminal Features ======
 +
 +~~TOC~~
 +
 +\\
 +This feature enables your integration to retrieve a terminal'​s configuration. This was introduced to facilitate the configuration of your integrations,​ enabling your solution to verify settings before sending requests and to avoid wrong requests and inconsistencies while integrating with the Payment Gateway.
 +
 +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.
 +
 +===== Get Terminal Configuration =====
 +
 +During the boarding process of a Merchant, one or a set of terminals is configured to process transactions. Many important settings, which could change over time to adapt to the Merchant'​s needs, are kept in these terminals'​ configuration section.
 +
 +Using this solution, you can consult a terminal'​s configuration in order to apply specific conditions and rules dynamically,​ without having to manually manage the changes in the terminal'​s configurations.
 +
 +  * **Main Request body Tag**: <​TERMINAL_CONFIGURATION> ​
 +  * **Main Response body Tag**: <​TERMINAL_CONFIGURATION_RESPONSE> ​
 +==== Request Body Fields ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| TERMINALID | Y  | A TerminalID provided by %CompanyName. |
 +| CUSTOM_FIELD_LANGUAGE |  N  | Language in which the custom fields of this given terminal should be retrieved in. Code, between 2 and 5 characters. |
 +| 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. For this specific feature, you should use the following formats:
 +
 +For this specific feature, you should consider the following format:
 +
 +<WRAP center box 100%>
 +TERMINALID:​CUSTOM_FIELD_LANGUAGE:​DATETIME:​SECRET
 +</​WRAP>​
 +\\
 +\\
 +
 +==== Examples for a Request ====
 +
 +  * **Scenario**:​ Request of terminal settings without custom fields language definition (gets default).
 +  * **Merchant**/​**Terminal**:​ 3614/​3614006.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF8"?>​
 +<​TERMINAL_CONFIGURATION>​
 +    <​TERMINALID>​3614006</​TERMINALID>​
 +    <​DATETIME>​06-03-2018:​17:​41:​08:​273</​DATETIME>​
 +    <​HASH>​44ada4060336a13b8d8a145c3f65865c</​HASH>​
 +</​TERMINAL_CONFIGURATION>​
 +</​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 will contain many of the main terminal settings. The Payment Gateway is going to send back the response and you need to prepare your integration to extract those settings. ​
 +The response body fields will be:
 +
 +<​searchtable>​
 +^ **FIELD** ^ **DESCRIPTION** ^
 +| TERMINALID | Same value as the one informed at the request. |
 +| CURRENCY ​  | Currency in which the terminal was configured to process transactions. A 3 character code following the ISO 4217 Currency Code. |
 +| ALLOW_MULTICURRENCY | Boolean defining if the terminal allows multicurrency processing. |
 +| ALLOW_EMCP - mandatory | Boolean defining if the terminal allows eMCP currency processing. |
 +| ALLOW_MOTO - mandatory | Boolean defining if the terminal allows MOTO operation. |
 +| ALLOW_INTERNET | Boolean defining if the terminal allows INTERNET integration. |
 +| ALLOW_EDCC | Boolean defining if the terminal allows eDCC currency processing. |
 +| ALLOW_CHP | Boolean defining if the terminal allows CHP transaction processing. |
 +| SUPPORTED_CURRENCIES | List of currencies suported by the Terminal to multicurrency processing of any kind. |
 +| (SECURE_CARD_STORAGE) ENABLED | Boolean defining if the terminal can store Secure Tokens. |
 +| (SECURE_CARD_STORAGE) ALLOW_SUBSCRIPTION | Boolean defining if the terminal can register Subscriptions. |
 +| (ENHANCED_DATA) ENABLED | Boolean defining if the terminal allows the use of enhanced data for transactions. |
 +| (ENHANCED_DATA) TXN_DATA_LEVEL | String defining if the terminal allows the use of enhanced data for transactions. It can be "​STANDARD",​ "LEVEL II", or "LEVEL III" - each ones allows more data to be used within the transaction. |
 +| (ENHANCED_DATA) API_ADDRESS_MODE | String defining the type of address mode used for fields regarding the enhanced data. It can be "​EXACT"​ (uses all of the address basic fields) or "​POSTAL"​ (only postal code is necessary). |
 +| SHOW_CVV - mandatory | Boolean defining if the terminal should show CVV on requests for transactions. |
 +| (AVS) ENABLED | Boolean defining if the terminal has AVS service enabled for transactions. |
 +| (AVS) COMPULSORY | Boolean defining, in case the terminal has the AVS service enabled, if the information of its fields is mandatory in requests. |
 +| (AVS) API_ADDRESS_MODE | Text defining, in case the terminal has the AVS service enabled, the address mode to be used for validation (can be EXACT or POSTAL). |
 +| ALLOW_MAX_MIND ​               | Boolean defining if the terminal has the MaxMind service enabled. |
 +| (SENTINEL_DEFEND) ENABLED | Boolean defining if the terminal has the Sentinel Defender service enabled. |
 +| (SENTINEL_DEFEND) ORGANIZATION_ID ​     | Id to identify the organization. |          ​
 +| (SENTINEL_DEFEND) FRAUDREVIEWSESSIONID | Id to identify the session to visualize fraud responses. |
 +| ENABLE_BACKGROUND_VALIDATION | Boolean defining if the terminal has the background validation feature enabled for HPP transactions. |
 +| ALLOW_ACH_JH | Boolean defining if the terminal allows processing of transactions via ACH Jack Henry. |
 +| CUSTOM_FIELDS | List of custom fields configured for the terminal, where each custom field is composed by: NAME/ DISPLAY_NAME/​ DISPLAY_ORDER/​ TYPE/ PAYMENT_PAGE/​ MANDATORY. |
 +| 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 consider the following format:
 +
 +<WRAP center box 100%>
 +TERMINALID:​ALLOW_MULTICURRENCY:​CURRENCY:​ALLOW_EMCP:​ALLOW_EDCC:​ALLOW_MOTO:​ALLOW_CHP:​ALLOW_INTERNET:​SUPPORTED_CURRENCIES[1]:​SECURE_CARD_STORAGE[2]:​ENHANCED_DATA[3]:​SHOW_CVV:​AVS[4]:​ALLOW_MAX_MIND:​SENTINEL_DEFEND[5]:​ENABLE_BACKGROUND_VALIDATION:​ALLOW_ACH_JH:​CUSTOM_FIELDS[6]:​DATETIME:​SECRET
 +</​WRAP>​
 +
 +  * **[1]** - **SUPPORTED_CURRENCIES**:​ concatenation of all the <​CURRENCY>​ elements returned within this field.
 +  * **[2]** - **SECURE_CARD_STORAGE**:​ concatenation of all the subelements of this element ( ENABLED:​ALLOW_SUBSCRIPTION ).
 +  * **[3]** - **ENHANCED_DATA**:​ concatenation of all the subelements of this element ( ENABLED:​TXN_DATA_LEVEL:​API_ADDRESS_MODE ).
 +  * **[4]** - **AVS**: concatenation of all the subelements of this element ( ENABLED:​COMPULSORY:​API_ADDRESS_MODE ).
 +  * **[5]** - **SENTINEL_DEFEND**:​ concatenation of all the subelements of this element ( ENABLED:​ORGANIZATION_ID:​FRAUDREVIEWSESSIONID ).
 +  * **[6]** - **CUSTOM_FIELDS**:​ concatenation of all the <​CUSTOM_FIELD>​ elements returned withing this field. Each CUSTOM_FIELD returned is going to be formed by the concatenation of all of its subelements:​ NAME:​DISPLAY_NAME:​DISPLAY_ORDER:​TYPE:​PAYMENT_PAGE:​MANDATORY.
 +\\
 +  ​
 +**ND002 - Response Codes - Errors **
 +
 +^ **ERROR CODE** ^ **DESCRIPTION** ^
 +| - | Invalid TERMINALID field |
 +| - | Terminal is not configured |
 +\\
 +
 +==== Examples for the Response ====
 +
 +  * **Scenario**:​ Response of the first request example.
 +  * **Merchant**/​**Terminal**:​ 3614/​3614006.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​TERMINAL_CONFIGURATION_RESPONSE>​
 +    <​TERMINALID>​3614006</​TERMINALID>​
 +    <​BANK_SETTINGS>​
 +        <​CURRENCY>​EUR</​CURRENCY>​
 +        <​ALLOW_MULTICURRENCY>​false</​ALLOW_MULTICURRENCY>​
 +        <​ALLOW_EMCP>​false</​ALLOW_EMCP>​
 +        <​ALLOW_EDCC>​true</​ALLOW_EDCC>​
 +        <​ALLOW_MOTO>​true</​ALLOW_MOTO>​
 +        <​ALLOW_CHP>​false</​ALLOW_CHP>​
 +        <​ALLOW_INTERNET>​true</​ALLOW_INTERNET>​
 +    </​BANK_SETTINGS>​
 +    <​SUPPORTED_CURRENCIES>​
 +        <​CURRENCY>​EUR</​CURRENCY>​
 +    </​SUPPORTED_CURRENCIES>​
 +    <​FEATURES>​
 +        <​SECURE_CARD_STORAGE>​
 +            <​ENABLED>​true</​ENABLED>​
 +            <​ALLOW_SUBSCRIPTION>​true</​ALLOW_SUBSCRIPTION>​
 +        </​SECURE_CARD_STORAGE>​
 +        <​ENHANCED_DATA>​
 +            <​ENABLED>​false</​ENABLED>​
 +            <​TXN_DATA_LEVEL>​LEVEL_II</​TXN_DATA_LEVEL>​
 +            <​API_ADDRESS_MODE>​POSTAL</​API_ADDRESS_MODE>​
 +        </​ENHANCED_DATA>​
 +    </​FEATURES>​
 +    <​SECURITY_FRAUD>​
 +        <​SHOW_CVV>​true</​SHOW_CVV>​
 +        <AVS>
 +            <​ENABLED>​false</​ENABLED>​
 +            <​COMPULSORY>​false</​COMPULSORY>​
 +        </​AVS>​
 +        <​ALLOW_MAX_MIND>​false</​ALLOW_MAX_MIND>​
 +        <​SENTINEL_DEFEND>​
 +            <​ENABLED>​false</​ENABLED>​
 +        </​SENTINEL_DEFEND>​
 +    </​SECURITY_FRAUD>​
 +    <​INTEGRATION>​
 +        <​ENABLE_BACKGROUND_VALIDATION>​true</​ENABLE_BACKGROUND_VALIDATION>​
 +    </​INTEGRATION>​
 +    <​ALLOW_ACH_JH>​false</​ALLOW_ACH_JH>​
 +    <​CUSTOM_FIELDS>​
 +        <​CUSTOM_FIELD>​
 +            <​NAME>​PRODUCT_SKU</​NAME>​
 +            <​DISPLAY_NAME>​Product SKU</​DISPLAY_NAME>​
 +            <​DISPLAY_ORDER>​1</​DISPLAY_ORDER>​
 +            <​TYPE>​STRING</​TYPE>​
 +            <​PAYMENT_PAGE>​true</​PAYMENT_PAGE>​
 +            <​MANDATORY>​false</​MANDATORY>​
 +        </​CUSTOM_FIELD>​
 +        <​CUSTOM_FIELD>​
 +            <​NAME>​AFFILIATE_ID</​NAME>​
 +            <​DISPLAY_NAME>​Affiliate ID</​DISPLAY_NAME>​
 +            <​DISPLAY_ORDER>​2</​DISPLAY_ORDER>​
 +            <​TYPE>​STRING</​TYPE>​
 +            <​PAYMENT_PAGE>​true</​PAYMENT_PAGE>​
 +            <​MANDATORY>​false</​MANDATORY>​
 +        </​CUSTOM_FIELD>​
 +    </​CUSTOM_FIELDS>​
 +    <​DATETIME>​29-03-2018:​17:​58:​31:​686</​DATETIME>​
 +    <​HASH>​44adsokrv986a13b8d8a145c92jsue12</​HASH>​
 +</​TERMINAL_CONFIGURATION_RESPONSE>​
 +</​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>​
 +
 +\\
  
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International