Table of Contents

Background Validation


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 Worldnet has a retry policy for background validations and this communication will be attempted multiple times.

This feature does not support bank transfers.

Request

Worldnet will use the validation webhook to send you an HTTP POST request containing the parameters below:

Filter:

FIELD DESCRIPTION
TERMINALID string [ 1 .. 50 ] characters
The terminal number assigned by Worldnet.
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.

The gateway expects your application to respond to this request with a plain 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 Worldnet. 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