Background Validation
Table of Contents
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 has a retry policy for background validations and this communication will be attempted multiple times.
Request
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 . |
| 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 <double> > 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 <enum> A: Approval E: Accepted (China Union Pay only) D: Declined R: Referral C: Pick Up For more details, visit Transaction Responses. |
| RESPONSETEXT | string [ 0 .. 48 ] characters A brief description sent by the processor about the transaction result. |
| DATETIME | string <date-time> 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 Transaction Responses for a full list of AVS response codes. |
| CVVRESPONSE | string 1 character The result of the CVV check. See Transaction Responses for a full list of CVV response codes. |
| HASH See notes: ND001 | string <SHA-512> [ 1 .. 128 ] characters A HASH code formed by part of the fields. |
| CUSTOMFIELD | Echoed back from the request. |
OK string. Any other response will lead to the transaction being flagged as not validated.
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 . See how to decode and validate a hash string at 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