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