Differences

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

Link to this comparison view

developer:api_specification:xml_account_verification_features [2019/05/16 10:24]
developer:api_specification:xml_account_verification_features [2022/07/15 15:23] (current)
Line 1: Line 1:
 +====== XML Account Verification Features ======
 +
 +~~TOC~~
 +
 +\\
 +The features presented in this page will allow your integration to check card accounts. This is a useful service for cases when you need to be sure a card is valid before using or storing it.
 +
 +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.
 +
 +\\
 +
 +===== Verification =====
 +
 +This feature allows you to check the vlidity of a card account.
 +
 +  * **Main Request body Tag**: <​ACCOUNT_VERIFICATION> ​
 +  * **Main Response body Tag**: <​ACCOUNT_VERIFICATION_RESPONSE> ​
 +  ​
 +==== Request Body Fields ====
 +
 +<​searchtable>​
 +^ **FIELD** ^ **REQUIRED** ^ **DESCRIPTION** ^
 +| TERMINALID ​    | Y | A Terminal ID provided by %CompanyName. |
 +| CARDNUMBER ​    | Y | The payment card number. |
 +| CARDEXPIRY ​    | Y | A 4 digit expiry field (MMYY). |
 +| 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. |
 +|ADDRESS1 | N | The first address. Required for AVS. |
 +|ADDRESS2 | N | Second line of address. Required for AVS. Same as ADDRESS1. |
 +|POSTCODE | N | Post code for the address. Required for AVS. |
 +| 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:​CARDNUMBER:​CARDEXPIRY:​CARDHOLDERNAME:​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 - The Checking Variation**
 +
 +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 check a card.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?> ​
 +<​ACCOUNT_VERIFICATION>​
 +    <​TERMINALID>​6491002</​TERMINALID>​
 +    <​CARDNUMBER>​4916163721669613</​CARDNUMBER>​
 +    <​CARDEXPIRY>​1122</​CARDEXPIRY>​
 +    <​CARDHOLDERNAME>​acc verif</​CARDHOLDERNAME>​
 +    <​CVV>​999</​CVV>​
 +    <​ADDRESS1>​addr 1</​ADDRESS1>​
 +    <​ADDRESS2>​addr 2</​ADDRESS2>​
 +    <​POSTCODE>​postcode</​POSTCODE>​
 +    <​DATETIME>​23-01-2019:​09:​24:​16:​105</​DATETIME>​
 +    <​HASH>​821cb691de21380b42efa97276ab0cc829c9fdfbcb28f5890492622c6a78093eeb28862b4d721e0e2f8db3a521eefda052da51979da6f66578a7b704b7c8aed5</​HASH>​
 +</​ACCOUNT_VERIFICATION>​
 +</​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** ^
 +| STATUS ​         | Verification result. VERIFIED when the check is successful or UNVERIFIED when the verification fails. |
 +| RESPONSE_DETAIL | This field adds context to the verification response, indicating in case or failure, the reason. |
 +| 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:​STATUS:​RESPONSE_DETAIL:​DATETIME:​SECRET
 +</​WRAP>​
 +
 +RESPONSE_DETAIL is only used if returned and TERMINALID refers the request field used.
 +
 +\\
 +
 +**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**:​ Response to the initial simple request.
 +  * **Terminal**:​ 6491002.
 +  * **Terminal Secret**: x4n35c32RT.
 +
 +<code xml>
 +<?xml version="​1.0"​ encoding="​UTF-8"?>​
 +<​ACCOUNT_VERIFICATION_RESPONSE>​
 +    <​STATUS>​UNVERIFIED</​STATUS>​
 +    <​RESPONSE_DETAIL>​CVV validation failed</​RESPONSE_DETAIL>​
 +    <​DATETIME>​29-04-2019:​15:​27:​45:​921</​DATETIME>​
 +    <​HASH>​d71730f0abb95321386bb7e29f13c0c55412c114ea8689f460a0ee68d0c23b300acecd5f88eae84366edcaee5dae121d356e2c10449b61e8319c7eedc19fe8f5</​HASH>​
 +</​ACCOUNT_VERIFICATION_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