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 for the following use case:
- New integrations with Payment Pages
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.
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.
Before proceeding, please contact our Support Team
- Our Support Team will enable site security on your site reference and will advise you on how to best configure your account.
- As part of this process, you will need to agree on the designated fields to be included in the hash generated (the list of default fields can be found in the table below).
- You will also need to agree on a password with our Support Team, to also be included when generating the hash. If you need to change this password, you will need to contact Support to action this.
Never share your site security password with third parties. Do not store hard copies of this password.
When site security is enabled, the default fields that will be used when generating the hash are as follows:
Note: We provide a walkthrough example of generating the hash below this table.
| Order | Field name | Type | Length | Description |
| 1 | currencyiso3a | Alpha | 3 |
The currency that the transaction will be processed in. |
| 2 | mainamount | Numeric | 14 |
The amount of the transaction in main units, using a decimal point to denote decimal values, so £10 is returned as 10.00.
Take care not to confuse this field with baseamount, which we use extensively in our API documentation, which is formatted in base units instead, forgoing the decimal point. |
| 3 | sitereference |
Alphanumeric including underscore |
50 | The unique Trust Payments site reference that relates to your individual account with us. If you do not know your site reference, please contact our Support Team. |
| 4 | settlestatus | Numeric | 3 |
A numeric value used to define the settlement instruction. If you do not submit a value here, the settlestatus defaults to “0”. |
| 5 | settleduedate | Date YYYY-MM-DD | 10 | You can submit this field in the request to specify the date you would like your transaction to settle. This must be within 7 days of the authorisation date. This date is returned in the response. |
| 6 | authmethod | Alpha | 5 |
Either: |
| 7 | paypaladdressoverride | Numeric | 1 | Only applicable to Payment Pages integrations: Specify how the delivery address is entered when processing payments with PayPal. |
| 8 | strequiredfields | Alphanumeric | Not defined |
Specify fields required to be entered by the customer. Multiple fields supported. If the customer fails to provide information in all the required fields or enters invalid information, the payment will not be completed. |
| 9 | version | Numeric | 1 | Only applicable to Payment Pages integrations: This value will be set to 2. |
| 10 | stprofile | Alphanumeric | Not defined | Only applicable to Payment Pages integrations: Used to specify the styling used to render the Payment Pages. When using the default appearance, this is set to “default” (click here for further information on profiles). |
| 11 | ruleidentifier | Alphanumeric including hyphens | Not defined |
You can submit unique identifiers for rules to be applied to this request (e.g. STR-1). |
| 12 | stdefaultprofile | Alphanumeric | Not defined |
Only applicable to Payment Pages integrations: We provide a number of default profiles that can be applied to each session. |
| 13 | successfulurlredirect | URL | Not defined | Only applicable to Payment Pages integrations: This is the URL the customer’s browser is redirected to following a successful transaction, when STR-6 is enabled. |
| 14 | declinedurlredirect | URL | Not defined | Only applicable to Payment Pages integrations: This is the URL the customer’s browser is redirected to following a declined transaction, when STR-7 is enabled. |
| 15 | successfulurlnotification | URL | Not defined | This is the URL the notification is sent to following a successful transaction, when STR-8 is enabled. |
| 16 | declinedurlnotification | URL | Not defined | This is the URL the notification is sent to following a declined transaction, when STR-9 is enabled. |
| 17 | merchantemail | Email address | 255 |
This is the email address to which any merchant email notifications are sent to, when STR-4 and/or STR-5 are enabled.
Maximum length of 255 (maximum of 64 characters before the ”@” symbol). |
| 18 | allurlnotification | URL | Not defined | This is the URL the notification is sent to following any request, when STR-10 is enabled. |
| 19 | stextraurlnotifyfields | Alphanumeric | Not defined | This is used to include additional fields in URL notifications. |
| 20 | stextraurlredirectfields | Alphanumeric | Not defined | This is used to include additional fields in URL redirects. |
| 21 | credentialsonfile | Numeric | 1 |
This is required for Visa and Mastercard transactions where the merchant is utilising the Credentials on File (CoF) feature. If the transaction is not eligible for CoF, or you do not wish to use credentials for future transactions, you can omit this field.
The allowed values for this field are 0, 1 & 2. 0 – Not eligible for CoF, or no intention of re-using credentials at a later time. 1 – Transaction credentials flagged as available for future use. 2 – Payment using previously-stored credentials. The above applies for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding. |
| 22 |
requesttypedescriptions |
List |
List of requesttypedescriptions submitted in the request.
Only applicable if using Enhanced post. |
|
| 23 | sitesecuritytimestamp | Date YYYY-MM-DD hh:mm:ss |
(Required in the hash – Must also be submitted in the request) As accurately as possible, the timestamp that reflects when the customer’s payment session was initiated. The customer will have 3 hours from the specified time to complete the payment.
Additional considerations:
|
|
| 24 | password | Alphanumeric including symbols | 255 |
(Required in the hash – Must NOT be submitted in the request) This is the site security password, as agreed with our Support Team.
Valid characters:
|
To add or remove fields from this list, please contact our Support Team. By including a field in your generated hash, this field cannot be modified by the customer or an unauthorised third party. We recommend including as many unique fields as possible. We support the inclusion of custom fields in your list of designated fields.
You must not include fields that the customer are allowed to modify after the post is submitted, for instance, in most cases their name, billing and delivery details. This can prevent legitimate transactions from being processed.
The customer’s IP address may change during the processing of a transaction, especially when browsing from mobile devices. For this reason, we recommend against opting to include this field as one of your designated fields.
Walkthrough example
Click the headings below to expand each step.
Append the values of the designated fields in the order shown above. For example, consider a request with the following fields:
currencyiso3a = GBP
mainamount = 100.00
sitereference = test_site12345
sitesecuritytimestamp = 2019-05-28 14:22:37
password = PASSWORDUsing this example, we would have the following string generated:
GBP100.00test_site123452019-05-28 14:22:37PASSWORD
(Any blank fields are omitted from the hash)
When appending the field values, ensure any white space characters present are not omitted from the string.
Site security timestamp
As accurately as possible, this timestamp should reflect the time the customer starts their payment session. (This timestamp value must NOT be in the future)
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 we will reject the request.
Order of the fields
When generating the hash, the fields must be in the same order as listed above. If the fields are not in the correct order, the request will fail.
The order in which fields are hashed can be changed if required. Please contact the Support Team for assistance.
The sitesecuritytimestamp and password fields must always be the last two fields in the string used to generate the hash. They cannot be re-positioned among the other fields or removed entirely.
Fields with multiple values
If a field included in the hash has multiple values, these values are concatenated in the order submitted in the POST.
Consider the following additional fields:
ruleidentifier=STR-7&ruleidentifier=STR-6
When included in the string generated above, it becomes:
GBP100.00test_site12345STR-7STR-62019-05-28 14:22:37PASSWORD
You will need to set up your system to generate the hash using the SHA-256 algorithm. When generating the hash, only the field values are used.
Example string:
GBP100.00test_site123452019-05-28 14:22:37PASSWORD
Hashing using SHA-256 will leave us with the following hash:
d08761660c77014d2a41d7dee54c2160863e2e560388601b71bae059d7f456ca
You can use the following code examples as a reference when generating your hash:
#!/usr/bin/python
import hashlib
stringToHash= "GBP100.00test_site123452019-05-28 14:22:37PASSWORD"
print hashlib.sha256(stringToHash).hexdigest()
<?php
echo hash("sha256", "GBP100.00test_site123452019-05-28 14:22:37PASSWORD");
?>
import java.math.BigInteger;
import java.security.MessageDigest;
public class mysha256 {
public static void main(String args[]) throws Exception {
String stringToHash = "GBP100.00test_site123452019-05-28 14:22:37PASSWORD";
MessageDigest digestObj = MessageDigest.getInstance("SHA-256");
digestObj.update(stringToHash.getBytes("UTF-8"));
String merchantHash = String.format("%064x",new BigInteger(1,digestObj.digest()));
System.out.println(merchantHash);
}
}
#!/usr/bin/perl
use Digest::SHA qw(sha256_hex);
$stringToHash = "GBP100.00test_site123452019-05-28 14:22:37PASSWORD";
$merchantHash = sha256_hex($stringToHash);
print $merchantHash;
Ensure your system submits the hash in lowercase
Failure to do so could invalidate the hash and stop legitimate transactions.
Example:
hd08761660c77014d2a41d7dee54c2160863e2e560388601b71bae059d7f456ca
This is the final value that would need to be submitted in the sitesecurity field for this transaction.
It is important that the generated hash is prefixed with the letter “h”.
This is to ensure the latest version of the site security feature is used.
Failure to do so could invalidate the hash and stop legitimate transactions.
You must ensure that you never POST the raw site security password (not hashed), as this is a shared secret between you and Trust Payments.
Troubleshooting advice for hosted Payment Pages
When testing your site security implementation and the Payment Pages returns error "There has been a problem with your payment - Invalid details", this indicates there has been a mismatch between the hash generated by your system and the value expected by Trust Payments. Please ensure you have followed all instructions provided above. If you are still having problems, please contact our Support Team for assistance.
