====== Background Validation ====== ~~TOC~~ \\ The background validation is an asynchronous webhook-based mechanism used to confirm wheher a transaction was processed or not. It comes in handy when the connection between the gateway and your application fails while you're still waiting for the response. This would leave the website in a hanging state, meaning that it'd be unable to give a feedback to the customer since it doesn't know whether the payment was processed or not. To use this feature, you need to enable it for your terminal. This can be done via our Selfcare System in the terminal setup section. Once enabled, all transactions processed through the hosted payment page will be validated. Additionally, you can also configure the **Validation URL** webhook in your terminal, so that you don't have to send it every time as part of the payment requests. If for some reason, the gateway is unable to establish a connection with your application and the validation fails, the transaction will be flagged as **expired** and a notification e-mail will be sent to the merchant. Please, keep in mind that %CompanyName has a retry policy for background validations and this communication will be attempted multiple times. ===== Request ===== %CompanyName will use the validation webhook to send you an ''HTTP POST'' request containing the parameters below: ^ **FIELD** ^ **DESCRIPTION** ^ | TERMINALID | ^{string ''[ 1 .. 50 ] characters''} \\ The terminal number assigned by %CompanyName. | | UNIQUEREF | ^{string ''10 characters''} \\ Unique reference number assigned by the gateway that should be stored to be able to perform follow up operations, such as reversals and refunds. | | AMOUNT | ^{number ''> 0''} \\ The transaction's total amount. | | ORDERID | ^{string ''[ 1 .. 24 ] characters''} \\ Echoed back from the request. | | APPROVALCODE | ^{string ''[ 0 .. 48 ] characters''} \\ The authorization code assigned by the payment processor for approved transactions. | | RESPONSECODE | ^string \\ ''A'': Approval \\ ''E'': Accepted (China Union Pay only) \\ ''D'': Declined \\ ''R'': Referral \\ ''C'': Pick Up \\ For more details, visit **[[selfcare:integration_docs:transaction_responses|Transaction Responses]]**. | | RESPONSETEXT | ^{string ''[ 0 .. 48 ] characters''} \\ A brief description sent by the processor about the transaction result. | | DATETIME | ^{string ''DD-MM-YYYY:HH:MM:SS:SSS''} \\ Same as the one generated for the transaction's response. | | AVSRESPONSE | ^{string ''1 character''} \\ The result of the AVS check. See **[[merchant:existing_merchant:other_information:transaction_responses|Transaction Responses]]** for a full list of AVS response codes. | | CVVRESPONSE | ^{string ''1 character''} \\ The result of the CVV check. See **[[merchant:existing_merchant:other_information:transaction_responses|Transaction Responses]]** for a full list of CVV response codes. | | HASH \\ ^{See notes: [[hosted_pages:hpp_background_validation#ND001 - Hash validation|ND001]]} | ^{string ''[ 1 .. 128 ] characters''} \\ A HASH code formed by part of the fields. | | CUSTOMFIELD | Echoed back from the request. | ==== Request notes ==== **ND001 - Hash validation** A hash string is also included in the request, so that you can implement a verification logic to make sure it was sent by %CompanyName. See how to decode and validate a hash string at **[[selfcare:api_specification:special_fields_and_parameters|Special Fields and Parameters]]**. For this specific feature, you should expect one of the following formats: * __For single currency terminals__: TERMINALID:ORDERID:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET * __For multi-currency terminals__: TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET