To protect your payments from unauthorised modification, you must follow the steps on this page to calculate a site security hash, to be submitted in a field called sitesecurity on your server-side payment form. The hash is generated from a selection of designated fields, including a password that will be agreed upon with our Support Team. When constructing the hash, you must ensure that you use the values present in your own server session and not the posted values.
Do I need it?
The configuration documented on this page is suitable in the following use-cases:
- New integrations with Payment Pages
- Digital wallet integrations that utilise our listener
This prevents the customer from modifying important aspects of the transaction (e.g. the amount and currency) before the authorisation request is submitted to us.
This configuration is not applicable in the following use-cases:
- Digital wallet integrations that utilise your own listener
- When using our API to host the checkout experience on your own server
How it works
We will read the fields in your request prior to processing an authorisation and re-generate the hash on our servers. For valid requests, the site security hash that we generate must match the value submitted in your request. This indicates the request has not been modified by the customer or a third party.
If someone tries to modify the value of one of your designated fields, the hash we calculate on our servers will not match the hash submitted in the request. In this case, the payment will not be completed and an error message is shown to the customer.
Generating site security hash
For Payment Pages
First, you will need to learn how to generate the site security hash:
Click here to open the instructions in a new tab on how to generate the sitesecurity hash.
Follow these instructions carefully and then look at the final step below to submit the hash in your POST.
When posting to the Payment Pages, you will need to include the sitesecurity and sitesecuritytimestamp fields in the POST, as shown below:
<html>
<head>
</head>
<body>
<!--YOUR HTML-->
<form method="POST" action="<DOMAIN>/process/payments/choice">
<input type="hidden" name="sitereference" value="test_site12345">
<input type="hidden" name="stprofile" value="default">
<input type="hidden" name="currencyiso3a" value="USD">
<input type="hidden" name="mainamount" value="100.00">
<input type="hidden" name="version" value="2">
<input type="hidden" name="orderreference" value="myorder12345">
<input type="hidden" name="sitesecurity" value="hee879a9ab97753b3a768925d50842f10e19fea03fef0b820026b6df92d415866">
<input type="hidden" name="sitesecuritytimestamp" value="2019-05-28 14:22:37">
<input type="submit" value="Pay">
</form>
</body>
</html>
Replace <DOMAIN> with a supported domain. Click here for a full list.
As accurately as possible, the sitesecuritytimestamp should reflect the time the customer’s browser is to be redirected to the Payment Pages.
The value submitted in this field must be in the format YYYY-MM-DD hh:mm:ss.
The timestamp must be in the UTC time zone. (e.g. “2019-05-28 14:22:37”)
The customer has 3 hours from the time specified to complete the transaction, otherwise an error will be displayed on screen.
For any payment that is attempted with an incorrect hash, the customer will be presented with an error (example below) and no payment will be processed:
