A working background validation implementation is required to certify your integration.
Background validation allows your application to securely capture and validate transactions using server-side application logic. It provides additional security, and is the means by which the payment gateway securely communicates back the result of a transaction. Implementing background validation is required for Hosted Payment Page transactions and is a prerequisite to certify your integration.
To validate a transaction, the payment gateway will perform an HTTP POST request on a predetermined validation URL within your application. This URL can be set through the SelfCare System in the Terminal Setup section.
This URL will be invoked for every individual transaction authorized on one of your terminals by the payment gateway. When calling this URL, the gateway will send a payload containing sufficient information to allow your application to confirm and validate the transaction. When receiving this call, your application should perform the following three actions:
Each step is documented in detail below. A complete background validation code sample can be found in our recommended sample integration.
This step is optional, but highly recommended. Verifying the transaction hash increases the security of your integration by ensuring that the submitted transaction originates from the payment gateway. The payment gateway is the only trusted entity capable of generating a valid hash value.
To verify the transaction hash, calculate the hash value of the request payload, and validate that it exactly matches the value found in the HASH field of the same payload. Hash calculation is detailed in the Special Fields and Parameters page, under the Hash Parameter section.
For background validation, use one of the following hash string format to calculate your hash value.
When using a Single Currency Terminal:
TERMINALID:ORDERID:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
When using a Multi Currency Terminal:
TERMINALID:ORDERID:CURRENCY:AMOUNT:DATETIME:RESPONSECODE:RESPONSETEXT:SECRET
This step is optional, but highly recommended. Verifying that the transaction originated from your own application ensures that it was not tampered with by a malicious actor.
To perform this validation, we recommend retrieving the original transaction request information from within your application storage and validating that the information received in the background validation payload corresponds to it.
The CUSTOMFIELD field of the payment request (see Payment and Pre-Authorization) can be leveraged to attach your own internal transaction identifier. The value of this field will be passed through to your background validation endpoint through a field of the same name on the request payload.
The gateway will consider a transaction "valid" if your background validation endpoint returns a status code 200 and the payload "OK" (the text characters 'O' and 'K', devoid of any markup). Any other status 200 response payload will result in the transaction being flagged as "invalid", which will effectively halt the transaction process before any exchange of funds will occur.
Should you detect any inconsistencies in Steps 1 or 2, your integration should return a different payload, effectively signaling to the gateway that the transaction is incorrect or did not originate from your application (i.e. you can respond "NOT OK" or any other text response).
The validation URL can be set either by specifying it in the transaction request payload using the VALIDATIONURL field (documentation here) or by going to the self care portal in the terminal settings page and setting the "Validation URL" (documentation here).
If you are a software vendor, we highly recommend passing the VALIDATIONURL parameter on each transaction as this confers direct control over the URL through your integration code. This allows the URL to be modified without requiring intervention from individual merchants, and prevents background validation failures due to configuration mishandling.
The validation URL will be invoked by the gateway for up to 96 hours, or 4 days, following an exponential backoff retry sequence. If the gateway is unable to get a status 200 response from the validation URL within this time frame, the transaction will be marked as "expired".
After 96 hours, an "expired" transaction will remain in the open batch until it is manually validated by logging into the SelfCare System. The merchant of record on the transaction will be notified via email that an expired transaction necessitates a manual validation. The notification email address is the email provided as the primary email in the merchant application.
Even though automatic retries will end after 96 hours, transactions that have "expired" can be manually validated as long as the authorization remains valid. Authorizations are typically valid for 7 to 30 days, depending on the financial institution.
| FIELD | DESCRIPTION |
|---|---|
| TERMINALID | Same as what was provided in the transaction's request. |
| UNIQUEREF | Generated reference that should be stored for tracking and remote XML refunding. |
| AMOUNT | Same as what was provided in the transaction's request. |
| ORDERID | Same as what was provided in the transaction's request. |
| RESPONSECODE | Same as the one generated for the transaction's response. |
| RESPONSETEXT | Same as the one generated for the transaction's response. Might be populated with an error, in case there was an issue during processing. |
| APPROVALCODE | Same as the one generated for the transaction's response. Might be empty, if the transaction was not approved. |
| DATETIME | Same as the one generated for the transaction's response. Format: YYYY-MM-DDTHH:MM:SS. |
| AVSRESPONSE | Same as the one generated for the transaction's response. |
| CVVRESPONSE | Same as the one generated for the transaction's response. |
| 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. |
| CUSTOMFIELD | Same as what was provided in the transaction's request. Returns all custom fields provided on request. |