Differences
This shows you the differences between two versions of the page.
|
developer:api_specification:xml_account_verification_features [2019/05/16 10:24] thiago123 created 5.9 release |
developer:api_specification:xml_account_verification_features [2022/10/07 14:38] (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> | ||
| + | \\ | ||