This shows you the differences between two versions of the page.
developer:api_specification:xml_account_verification_features [2019/05/16 11: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> | ||
+ | \\ | ||