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_secure_card_features [2018/07/11 15:38]
127.0.0.1 external edit
developer:api_specification:xml_secure_card_features [2019/06/10 08:19] (current)
Line 1: Line 1:
 +====== XML Secure Card Features ======
 +
 +~~TOC~~
 +
 +\\
 +The features presented in this page will allow your integration to create and manage the lifecycle of a Secure Card. You can read more about the Secure Card feature in **[[merchant:​new_merchant:​products#​secure_card| Products - Secure Card]]**.
 +
 +<WRAP center info 100%>
 +You also can register and update Secure Cards using the HP integration method directly, or also, during HP or XML payment transactions,​ to easy your implementation effort. If that interests you, go back those sections and take a look at how to do that with minimum effort, but remember: just the present features allow you to search for Secure Cards.
 +</​WRAP>​
 +
 +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.
 +
 +\\
 +
 +===== Registration =====
 +
 +This feature allows you to perform the registration of a Secure Card.
 +
 +  * **Main Request body Tag**: <​SECURECARDREGISTRATION> ​
 +  * **Main Response body Tag**: <​SECURECARDREGISTRATIONRESPONSE> ​
 +  ​
 +==== Request Body Fields ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| MERCHANTREF ​        | Y | Unique Merchant Reference. Length is limited to 48 chars. |
 +| TERMINALID ​         | Y | A Terminal ID provided by %CompanyName. |
 +| CARDNUMBER ​ | Y | The payment card number. ​                                                                                       |
 +| CARDEXPIRY ​ | Y | A 4 digit expiry field (MMYY). ​                                                                                   |
 +| CARDTYPE | Y | Card Type used for the registration.\\ For more details on this, visit **[[developer:​api_specification:​special_fields_and_parameters#​the_card_types|Special Fields and Parameters - Card Types]]**. |
 +| CARDHOLDERNAME | Y | The name of the card holder. It should be as displayed on the front of the card. |
 +| CVV                 | N | The security code entered by the card holder. Take a look at **ND003 - CVV Checking**. |
 +| ISSUENO ​            | N | The issue  no. of the card (Solo). |
 +| 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 3 custom fields in this request. |
 +| EMAIL               | N | Cardholders e-mail address. If populated the cardholder will be sent an email receipt. This can be overridden by %SelfCare Terminal Setup settings "​Disable Cardholder Receipt"​. |
 +| PHONE               | N | Card Holder Phone Number stored against transaction. International format, numeric only. |
 +| 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:​CARDNUMBER:​CARDEXPIRY:​CARDTYPE:​CARDHOLDERNAME:​SECRET
 +</​WRAP>​
 +\\
 +
 +**ND002 - Data Encoding for Requests**
 +
 +All data sent to us should be correctly encoded using **UTF-8** as the character encoding.
 +
 +\\
 +
 +**ND003 - CVV Checking**
 +
 +If a Terminal is configured to perform secure card validation (CVV mandatory or not), the Payment Gateway performs an account verification before registering the Secure Card:
 +
 +  * If the CVV field is informed, the CVV response returned is verified and if it's positive the secure card is registered, if not, an error is generated.
 +  * If the CVV field is not informed, the result of the transaction is verified and if it's successful the secure card is registered, if not, an error is generated.
 +
 +Depending on the Payment Processor used by the Terminal, the account verification can be performed in two distinct ways: 
 +  * A 0.00 (zero) amount transaction or,
 +  * A 1.00 (one) currency unit amount transaction followed, when successful, by its voiding (both transactions will appear in your batch).
 +
 +\\
 +
 +==== Examples for a Request ====
 +
 +  * **Scenario**:​ Simple request to register a secure card.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?> ​
 +<​SECURECARDREGISTRATION>​
 +    <​MERCHANTREF>​77001</​MERCHANTREF>  ​
 +    <​TERMINALID>​6491002</​TERMINALID>  ​
 +    <​DATETIME>​31-12-2008:​23:​59:​59:​001</​DATETIME>​
 +    <​CARDNUMBER>​4444333322221111</​CARDNUMBER>  ​
 +    <​CARDEXPIRY>​1208</​CARDEXPIRY>  ​
 +    <​CARDTYPE>​VISA</​CARDTYPE>  ​
 +    <​CARDHOLDERNAME>​John Smith<​CARDHOLDERNAME>​
 +    <​HASH>​d04c3bab519095ecb046eff91722e8df</​HASH>​
 +</​SECURECARDREGISTRATION> ​
 +</​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. |
 +| CARDREFERENCE | This field represents the token generated for the Secure Card. |
 +| 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:​CARDREFERENCE:​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 |
 +| E04 | INVALID REFERENCE DETAILS |
 +| E05 | INVALID CARD TYPE |
 +| E06 | INVALID TERMINALID |
 +| E07 | METHOD NOT SUPPORTED |
 +| E08 | INVALID MERCHANTREF |
 +| E09 | INVALID DATETIME |
 +| E10 | INVALID CARDNUMBER |
 +| E11 | INVALID CARDEXPIRY |
 +| E12 | INVALID CARDHOLDERNAME |
 +| E13 | INVALID HASH |
 +| E14 | INVALID SECURITY FIELD |
 +\\
 +
 +
 +==== Examples for the Response ====
 +
 +  * **Scenario**:​ Response to the initial simple request.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​SECURECARDREGISTRATIONRESPONSE>  ​
 +    <​MERCHANTREF>​77001</​MERCHANTREF>  ​
 +    <​CARDREFERENCE>​2999990000000001</​CARDREFERENCE>  ​
 +    <​DATETIME>​31-12-2008:​23:​59:​59:​002</​DATETIME>​
 +    <​HASH>​d04c3bab519095ecb046eff91722e8df</​HASH> ​      
 +</​SECURECARDREGISTRATIONRESPONSE>​
 +</​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>​
 +\\
 +
 +===== Update =====
 +
 +This feature allows you to perform the update of an existing Secure Card.
 +
 +  * **Main Request body Tag**: <​SECURECARDUPDATE> ​
 +  * **Main Response body Tag**: <​SECURECARDUPDATERESPONSE> ​
 +  ​
 +==== Request Body Fields ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| MERCHANTREF ​        | Y | Unique Merchant Reference. Length is limited to 48 chars. |
 +| TERMINALID ​         | Y | A Terminal ID provided by %CompanyName. |
 +| CARDNUMBER ​ | N | The payment card number. ​                                                                                       |
 +| CARDEXPIRY ​ | N | A 4 digit expiry field (MMYY). ​                                                                                   |
 +| CARDTYPE | N | Card Type used for the registration.\\ For more details on this, visit **[[developer:​api_specification:​special_fields_and_parameters#​the_card_types|Special Fields and Parameters - Card Types]]**. |
 +| CARDHOLDERNAME | N | The name of the card holder. It should be as displayed on the front of the card. |
 +| CVV                 | N | The security code entered by the card holder. Take a look at **ND003 - CVV Checking**. |
 +| ISSUENO ​            | N | The issue  no. of the card (Solo). |
 +| 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 3 custom fields in this request. |
 +| EMAIL               | N | Cardholders e-mail address. If populated the cardholder will be sent an email receipt. This can be overridden by %SelfCare Terminal Setup settings "​Disable Cardholder Receipt"​. |
 +| PHONE               | N | Card Holder Phone Number stored against transaction. International format, numeric only. |
 +| 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:​CARDNUMBER:​CARDEXPIRY:​CARDTYPE:​CARDHOLDERNAME:​SECRET
 +</​WRAP>​
 +\\
 +
 +**ND002 - Data Encoding for Requests**
 +
 +All data sent to us should be correctly encoded using **UTF-8** as the character encoding.
 +
 +\\
 +
 +**ND003 - CVV Checking**
 +
 +If a Terminal is configured to perform secure card validation (CVV mandatory or not), the Payment Gateway performs an account verification before registering the Secure Card:
 +
 +  * If the CVV field is informed, the CVV response returned is verified and if it's positive the secure card is registered, if not, an error is generated.
 +  * If the CVV field is not informed, the result of the transaction is verified and if it's successful the secure card is registered, if not, an error is generated.
 +
 +Depending on the Payment Processor used by the Terminal, the account verification can be performed in two distinct ways: 
 +  * A 0.00 (zero) amount transaction or,
 +  * A 1.00 (one) currency unit amount transaction followed, when successful, by its voiding (both transactions will appear in your batch).
 +
 +\\
 +
 +==== Examples for a Request ====
 +
 +  * **Scenario**:​ Simple request to update a secure card.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​SECURECARDUPDATE>​
 + <​MERCHANTREF>​77001</​MERCHANTREF>​
 + <​TERMINALID>​6491002</​TERMINALID>​
 + <​DATETIME>​31-12-2008:​23:​59:​59:​001</​DATETIME>​
 + <​CARDEXPIRY>​1208</​CARDEXPIRY>​
 + <​CARDTYPE>​VISA</​CARDTYPE>​
 + <​HASH>​d04c3bab519095ecb046eff91722e8df</​HASH>​
 +</​SECURECARDUPDATE>​
 +</​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. |
 +| CARDREFERENCE | This field represents the token generated for the Secure Card. |
 +| 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:​CARDREFERENCE:​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 |
 +| E04 | INVALID REFERENCE DETAILS |
 +| E05 | INVALID CARD TYPE |
 +| E06 | INVALID TERMINALID |
 +| E07 | METHOD NOT SUPPORTED |
 +| E08 | INVALID MERCHANTREF |
 +| E09 | INVALID DATETIME |
 +| E10 | INVALID CARDNUMBER |
 +| E11 | INVALID CARDEXPIRY |
 +| E12 | INVALID CARDHOLDERNAME |
 +| E13 | INVALID HASH |
 +| E14 | INVALID SECURITY FIELD |
 +\\
 +
 +==== Examples for the Response ====
 +
 +  * **Scenario**:​ Response to the initial simple request.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​SECURECARDREGISTRATIONRESPONSE>  ​
 +    <​MERCHANTREF>​77001</​MERCHANTREF>  ​
 +    <​CARDREFERENCE>​2999990000000001</​CARDREFERENCE>  ​
 +    <​DATETIME>​31-12-2008:​23:​59:​59:​002</​DATETIME>​
 +    <​HASH>​d04c3bab519095ecb046eff91722e8df</​HASH> ​      
 +</​SECURECARDREGISTRATIONRESPONSE>​
 +</​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>​
 +\\
 +
 +===== Removal =====
 +
 +This feature allows you to perform the removal of an existing Secure Card.
 +
 +  * **Main Request body Tag**: <​SECURECARDREMOVAL> ​
 +  * **Main Response body Tag**: <​SECURECARDREMOVALRESPONSE> ​
 +  ​
 +==== Request Body Fields ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| MERCHANTREF ​        | Y | Unique Merchant Reference. Length is limited to 48 chars. See **ND003 - Not Reusable Merchant Ref**. |
 +| TERMINALID ​         | Y | A Terminal ID provided by %CompanyName. |
 +| CARDREFERENCE ​      | Y | The reference of the Secure Card you want to remove. |
 +| 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:​CARDREFERENCE:​SECRET
 +</​WRAP>​
 +\\
 +
 +**ND002 - Data Encoding for Requests**
 +
 +All data sent to us should be correctly encoded using **UTF-8** as the character encoding.
 +
 +\\
 +
 +**ND003 - Not Reusable Merchant Ref**
 +
 +The Merchant Reference is unique, so once a Secure Card is removed, its MerchantRef can't be resused. This is because they are tied to existing transactions in our system and are retained internally for data integrity and future refund functionality.
 +\\
 +
 +==== Examples for a Request ====
 +
 +  * **Scenario**:​ Simple request to remove a secure card.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?> ​
 +<​SECURECARDREMOVAL>  ​
 +      <​MERCHANTREF>​77001</​MERCHANTREF>  ​
 +      <​CARDREFERENCE>​2967534771694736</​CARDREFERENCE>  ​
 +      <​TERMINALID>​6491002</​TERMINALID>  ​
 +      <​DATETIME>​31-12-2008:​23:​59:​59:​001</​DATETIME>​
 +      <​HASH>​d04c3bab519095ecb046eff91722e8df</​HASH> ​       ​
 +</​SECURECARDREMOVAL>​
 +</​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:​CARDREFERENCE:​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 |
 +| E04 | INVALID REFERENCE DETAILS |
 +| E06 | INVALID TERMINALID |
 +| E07 | METHOD NOT SUPPORTED |
 +| E08 | INVALID MERCHANTREF |
 +| E13 | INVALID HASH |
 +\\
 +
 +==== Examples for the Response ====
 +
 +  * **Scenario**:​ Response to the initial simple request.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​SECURECARDREMOVALRESPONSE>  ​
 +      <​MERCHANTREF>​77001</​MERCHANTREF>  ​
 +      <​DATETIME>​31-12-2008:​23:​59:​59:​002</​DATETIME>​
 +      <​HASH>​d04c3bab519095ecb046eff91722e8df</​HASH> ​     ​
 +</​SECURECARDREMOVALRESPONSE>​
 +</​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>​
 +\\
 +
 +
 +===== Search =====
 +
 +This feature allows you to retrieve a specific Secure Card and its details.
 +
 +  * **Main Request body Tag**: <​SECURECARDSEARCH> ​
 +  * **Main Response body Tag**: <​SECURECARDSEARCHRESPONSE> ​
 +  ​
 +==== Request Body Fields ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| MERCHANTREF ​        | Y | Unique Merchant Reference. 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 search a secure card.
 +  * **Merchant Reference**:​ 77001.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​SECURECARDSEARCH>​
 + <​MERCHANTREF>​77001</​MERCHANTREF>​
 + <​TERMINALID>​6491002</​TERMINALID>​
 + <​DATETIME>​31-12-2008:​23:​59:​59:​001</​DATETIME>​
 + <​HASH>​d04c3bab519095ecb046eff91722e8df</​HASH>​
 +</​SECURECARDSEARCH>​
 +</​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. |
 +| CARDREFERENCE | This field represents the token generated for the Secure Card. |
 +| CARDTYPE | Card Type used for the registration. |
 +| CARDEXPIRY | Card Expiry used for registration. A 4 digit expiry field (MMYY).|
 +| CARDHOLDERNAME | The name of the card holder used for registration. |
 +| 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:​CARDREFERENCE:​CARDTYPE:​CARDEXPIRY:​CARDHOLDERNAME:​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 |
 +| E04 | INVALID REFERENCE DETAILS |
 +| E06 | INVALID TERMINALID |
 +| E07 | METHOD NOT SUPPORTED |
 +| E08 | INVALID MERCHANTREF |
 +| E13 | INVALID HASH |
 +| E34 | SECURE CARD WAS NOT FOUND |
 +| E35 | SECURE CARD WAS DELETED |
 +\\
 +
 +==== Examples for the Response ====
 +
 +  * **Scenario**:​ Response to the initial simple request.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​SECURECARDSEARCHRESPONSE>​
 + <​MERCHANTREF>​77001</​MERCHANTREF>​
 + <​CARDREFERENCE>​2967532702149716</​CARDREFERENCE>​
 + <​CARDTYPE>​VISA</​CARDTYPE>​
 + <​CARDEXPIRY>​1208</​CARDEXPIRY>​
 + <​CARDHOLDERNAME>​Joe Smith<​CARDHOLDERNAME>​
 + <​DATETIME>​31-12-2008:​23:​59:​59:​001</​DATETIME>​
 + <​HASH>​d04c3bab519095ecb046eff91722e8df</​HASH>​
 +</​SECURECARDSEARCHRESPONSE>​
 +</​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>​
 +\\
 +
 +
 +===== Advanced Search =====
 +
 +This feature allows you to retrieve a list of Secure Cards and their details. With this feature, you are going to be able to add criteria for a search, like: name, date, e-mail, phone and even custom fields (up to 3), as neede
 +
 +  * **Main Request body Tag**: <​SECURE_CARD_ADVANCED_SEARCH> ​
 +  * **Main Response body Tag**: <​SECURE_CARD_ADVANCED_SEARCH_RESPONSE> ​
 +  ​
 +==== Request Body Fields ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| MERCHANTREF ​        | Y | Unique Merchant Reference. Length is limited to 48 chars. |
 +| TERMINALID ​         | Y | A Terminal ID provided by %CompanyName. |
 +| NAME | N | Card holder’s name used for the Secure Card registration. |
 +| EMAIL | N | Card holder’s email used for the Secure Card registration. |
 +| PHONE   | N | Card holder’s phone used for the Secure Card registration. |
 +| CREATIONDATE | N | Creation date of the Secure Card. Format: DD-MM-YYYY.|
 +| 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. To understand more visit the section regarding **[[developer:​api_specification:​special_fields_and_parameters|Special Fields and Parameters]]**. Limited to 3 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:​NAME:​EMAIL:​PHONE:​CREATIONDATE:​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 retrieve a list of secure cards.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​SECURE_CARD_ADVANCED_SEARCH>​
 + <​MERCHANTREF>​77001</​MERCHANTREF>​
 + <​TERMINALID>​6491002</​TERMINALID>​
 + <​NAME>​John Smith</​NAME>​
 + <​EMAIL>​john@selfdomain.com</​EMAIL>​
 + <​PHONE>​11856452420</​PHONE>​
 + <​CREATIONDATE>​31-12-2008</​CREATIONDATE>​
 + <​DATETIME>​11-6-2017:​11:​23:​55:​134 </​DATETIME>​
 + <​HASH>​d04c3bab519095ecb046eff91722e8df</​HASH>​
 +</​SECURE_CARD_ADVANCED_SEARCH>​
 +</​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** ^
 +| SECURECARD | List of Secure Cards registered, which matched the search criteria. Each secure card contains a set of subelements as defined in **ND002 - Secure Card Elements**. |
 +| 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[1]:​CARDREFERENCE[1]:​CARDHOLDERNAME[1]:​DATETIME:​SECRET
 +</​WRAP>​
 +
 +  * **[1]** - **MERCHANTREF**/​**CARDREFERENCE**/​**CARDHOLDERNAME**:​ The HASH should contain the concatenation of all the strings representing each secure card returned, in the sequence they were returned. The string of each secure card should be formed by the concatenation of these tree elements.
 +
 +\\
 +
 +**ND002 - Secure Card Elements**
 +
 +Each secure card returned by the search has a set of nested elements, as defined below:
 +
 +^ **FIELD** ^ **DESCRIPTION** ^
 +| MERCHANTREF | Same as the one informed on request. |
 +| CARDREFERENCE | This field represents the token generated for the Secure Card. |
 +| CARDTYPE | Card Type used for the registration. |
 +| CARDEXPIRY | Card Expiry used for registration. A 4 digit expiry field (MMYY).|
 +| CARDHOLDERNAME | The name of the card holder used for registration. |
 +\\
 +
 +**ND003 - 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>​
 +\\
 +
 +**ND004 - 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 |
 +| E13 | INVALID HASH |
 +| E34 | SECURE CARD WAS NOT FOUND |
 +| E35 | SECURE CARD WAS DELETED |
 +\\
 +
 +==== Examples for the Response ====
 +
 +  * **Scenario**:​ Response to the initial simple request.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​SECURE_CARD_ADVANCED_SEARCH_RESPONSE>​
 + <​SECURECARD>​
 + <​MERCHANTREF>​77001</​MERCHANTREF>​
 + <​CARDREFERENCE>​72357598079</​CARDREFERENCE>​
 + <​CARDTYPE>​DISCOVERY</​CARDTYPE>​
 + <​CARDEXPIRY>​1019</​CARDEXPIRY>​
 + <​CARDHOLDERNAME>​Joan Simons</​CARDHOLDERNAME>​
 + </​SECURECARD>​
 + <​SECURECARD>​
 + <​MERCHANTREF>​77001</​MERCHANTREF>​
 + <​CARDREFERENCE>​12465693334</​CARDREFERENCE>​
 + <​CARDTYPE>​VISA</​CARDTYPE>​
 + <​CARDEXPIRY>​1217</​CARDEXPIRY>​
 + <​CARDHOLDERNAME>​Phelippo Henry Sibouer</​CARDHOLDERNAME>​
 + </​SECURECARD>​
 + <!-- Until 10 Secure Card registries are returned -->
 + <​DATETIME>​29-06-2017:​09:​52:​12:​650</​DATETIME>​
 + <​HASH>​a978a30afd8303cd24035d8bad6692d7]</​HASH>​
 +</​SECURE_CARD_ADVANCED_SEARCH_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