Generating site security hash

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.

Click here for a full list of available currencies.

2 mainamount Numeric 14 The amount of the transaction in main unitsusing 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
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”.

Click here for a full list of settlestatus values.

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


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).

Click here for further information.

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.

Click here to learn more.

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.



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:

  • The timestamp value must be in UTC.
  • The timestamp value must NOT be in the future.
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:

  • Uppercase and lowercase letters
  • Numbers 0-9
  • Spaces
  • ~ ! # $ % ^ & * ( ) _ { } [ ] < > , ?


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.

Step 1: Prepare the string

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 = PASSWORD

Using 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:

When included in the string generated above, it becomes:
GBP100.00test_site12345STR-7STR-62019-05-28 14:22:37PASSWORD

Step 2: Hash the string

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:


You can use the following code examples as a reference when generating your hash:

Python PHP Java Perl

import hashlib
stringToHash= "GBP100.00test_site123452019-05-28 14:22:37PASSWORD"
print hashlib.sha256(stringToHash).hexdigest()

  Ensure your system submits the hash in lowercase

Failure to do so could invalidate the hash and stop legitimate transactions.

Step 3: Precede hash with h



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.

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request