Contents

Site security

 

To protect your payments from unauthorised modification, you can 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.

 

 

 

 

 

 

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.

Warning
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
underscore
50 The unique Secure Trading 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 Either “PRE” or “FINAL”.
Click here for further information.
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 only applies if you are processing payments with certain acquiring banks. Contact our Support Team for further information.

22 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.
23 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.

Warning
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

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

 

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

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

Info
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

Step 2: Hash the string

2
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;

Step 3: Precede hash with h

3
Precede the hash with a “h”:


hD08761660C77014D2A41D7DEE54C2160863E2E560388601B71BAE059D7F456CA

 

This is the final value that would need to be submitted in the sitesecurity field for this transaction.

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

 


 

Padlock
You must ensure that you never POST the raw site security password (not hashed), as this is a shared secret between you and Secure Trading.