cachetoken – Documentation

JavaScript Library (version 1)

This page documents how to integrate using our legacy JavaScript Library solution (verson 1)

If you are integrating with us for the first time, we strongly recommend using the latest version of our JavaScript Library.

Click here to get started >>>

Install a library

We provide libraries for the Python and PHP programming languages. Alternatively, it is possible to use cURL in a variety of other languages. These libraries consist of functions that can be referenced within your program body without defining them explicitly.

We recommend that you follow the instructions below to download and install your preferred library on your server.

Planning on using your own library?

If you plan on using your own library to process requests, you will need to read “Configuring your own library“.

Python

We support Python v2.7.9+ and v3.
We recommend that you use the latest version of Python v3.x available when integrating with us.
Python v2.7 reaches end of life in January 2020. As such, we strongly recommend against new integrations using this version.
Version “2.9” of the Python “requests” library is required to ensure that the latest certificates have been installed.

To install our Python library, you can use ‘pip‘, which is a package management system used to install and manage software packages written in Python.

Using pip

pip install securetrading

Alternatively, you can download the package from https://github.com/Secure-Trading/st-python-api and install the library manually.

PHP

You can use the following command to install our PHP library.

Composer is a tool for dependency management in PHP. It allows you to declare the libraries your project depends on and it will install and update them for you.

Using composer

composer require securetrading/stpp_json

cURL

Provided your system already has cURL installed, no additional installation is required.

You must never log sensitive payment details on your server

Please ensure that any additional debugging enabled whilst testing your integration is disabled prior to going live. Failing to do so may contravene the requirements needed to maintain PCI compliance.

Summary

You have now installed a library on your server, and you can use this to send requests to our gateway.

Read on to learn how to process your first request.

Collecting payment details using Cachetoken

You can use our JavaScript Client SDK (“st.js”) to process payments without submitting the customer’s card details to your server, thereby simplifying the audit process for PCI DSS.

Your server-side payment form must assign all card details with the attribute “data-st-field”. During payment form submission, “st.js” will tokenise all fields with the attribute “data-st-field” to create a unique cachetoken.

This cachetoken is then submitted to your server, along with all other fields that do not have the attribute “data-st-field”.

Server-side payment form

The following is an example of a payment form:

Standard
Overriding id

<html>

<head>
    <style>
        #st-payment input.st-error {
            background-color: #ffc6c7;
            border: 2px solid #ffb5b5;
        }
        #st-message .st-error {
            background: #ffcdcd;
            border: 2px solid #ffb5b5;
            padding: 4px 4px 4px 28px !important;
        }
    </style>
</head>

<body>
    <div id="st-message"></div>
    <form id="st-payment" action="https://www.example.com">
    <!--Ensure all payment details use the data-st-field attribute.-->
        Pan: 
        <input type="text" data-st-field="pan" autocomplete="off" /></br>
        Expiry Month: 
        <input type="text" data-st-field="expirymonth" autocomplete="off" /></br>
        Expiry Year: 
        <input type="text" data-st-field="expiryyear" autocomplete="off" /></br>
        Security Code: 
        <input type="text" data-st-field="securitycode" autocomplete="off" /></br>
    <!--You can submit your own custom fields within this form, e.g. discount code-->
        Discount Code: 
        <input type="text" name="discountcode" autocomplete="off" /></br>
        <input type="submit" name="mybtn" />
    </form>
    <script src="https://webservices.securetrading.net/js/st.js"></script>
    <script>
        new SecureTrading.Standard({
            sitereference: "test_site12345", locale: "en_gb"
        });
    </script>
</body>
</html>

<html>

<!-- If you need to change the names of the identifiers “st-message” and “st-payment”, -->
<!-- because your application doesn’t support the naming convention used -->
<!-- (e.g. no hyphen support), you can use the markup found here to override them. -->

<head>
    <style>
        #st-payment input.st-error {
            background-color: #ffc6c7;
            border: 2px solid #ffb5b5;
        }
        #st-message .st-error {
            background: #ffcdcd;
            border: 2px solid #ffb5b5;
            padding: 4px 4px 4px 28px !important;
        }
    </style>
</head>

<body>
    <div id="stmessage"></div>
    <form id="stpayment" action="https://www.example.com">
    <!--Ensure all payment details use the data-st-field attribute.-->
        Pan: 
        <input type="text" data-st-field="pan" autocomplete="off" /></br>
        Expiry Month: 
        <input type="text" data-st-field="expirymonth" autocomplete="off" /></br>
        Expiry Year: 
        <input type="text" data-st-field="expiryyear" autocomplete="off" /></br>
        Security Code: 
        <input type="text" data-st-field="securitycode" autocomplete="off" /></br>
    <!--You can submit your own custom fields within this form, e.g. discount code-->
        Discount Code: 
        <input type="text" name="discountcode" autocomplete="off" /></br>
        <input type="submit" name="mybtn" />
    </form>
    <script src="https://webservices.securetrading.net/js/st.js"></script>
    <script>
        new SecureTrading.Standard({
            sitereference: "test_site12345",
            locale: "en_gb",
            messageId: "stmessage",
            formId: "stpayment",
        });
    </script>
</body>
</html>

To use the Client SDK, reference our “st.js” in your webpage’s HTML mark-up, as demonstrated in the payment form example above.

You must ensure that your payment form has been assigned the id “st-payment”. The following are required fields and must be included in the payment form:

The card number: data-st-field=”pan”
The card expiry month: data-st-field=”expirymonth”
The card expiry year: data-st-field=”expiryyear”
The card security code: data-st-field=”securitycode”

After the customer clicks “Pay”, these fields are used to generate a unique cachetoken that will later be posted to your server, for the purpose of processing requests.

The cachetoken will expire 15 minutes after being generated.

You must ensure that the PAN, expiry date and security code use the “data-st-field” attribute and NOT the “name” attribute. Failing to do so may lead to sensitive data being posted directly to your server.

Any input fields that have the attribute “data-st-field” are transmitted directly to Trust Payments from the customer’s browser session in a secure manner. This means that these sensitive payment details are never submitted to your server.

A “div” element with attribute id=”st-message” is required, in order for invalid field and connection errors to be displayed, in cases when ‘st.js’ fails to generate a cachetoken.

If there is an error during the cachetoken generation process, the optional CSS included in the server-side payment form example will highlight any invalid input fields on the form and style the error message returned.

This library supports the AMD (Asynchronous Module Definition) API. This allows it to be loaded using RequireJS, CommonJS or through a normal <script> element inside your webpage’s HTML markup.

Ensure the action in the server-side payment form is a valid URL address hosted on your server. The address specified must be able to take the generated cachetoken and all fields without the “data-st-field” attribute, which are submitted to the Server SDK as a JSON request.

Callback prior to processing a payment

If you need to perform additional tasks after the cachetoken has been passed to the customer’s browser session, but before the payment form details are submitted to your server, you can do so by passing the submitFormCallback parameter to the SecureTrading.Standard library.

Callback function

new SecureTrading.Standard({
    sitereference: "test_site12345",
    submitFormCallback: function(responseObj){
    var cachetoken = responseObj['response'][0]['cachetoken']; <!-- Grab token -->
    console.log(cachetoken); <!-- Logs the token to the console (Additional steps can be performed here before submitting to your server) -->
    document.getElementById(‘st-payment’).submit(); <!-- Submit the form -->
}

Language support

The response messages can be returned to the customer in the following languages:

English
French
German

By default, the response is returned in English. In order to change the default language, simply change the locale value in the payment form example above.

To return the response in the English language, set the locale to ‘en_gb’.
To return the response in the French language, set the locale to ‘fr_fr’.
To return the response in the German language, set the locale to ‘de_de’.

An example of a message returned to the customer – “There has been a problem with your payment, please verify your details and try again.”

Test credentials

You can process successful transactions by submitting the following test card numbers:

Payment type	Test PAN	Expiry date	Security code
Visa	4111111111111111	12/2030	123
Mastercard	5100000000000511	12/2030	123

Note: Any expiry date submitted to our test bank is valid, providing the date is in the future.

Other cards are supported. Click here for further testing credentials.

Summary

You should now have a basic form that can be used to collect the customer’s payment details and send a cachetoken to your server.
The cachetoken can be used in conjunction with your installed library to process a request.

Process requests using our Webservices API

The following describes how you can reference the SDK functions within your program body to submit a request to our servers.

Before you get started, you will need a Web Services username and password to allow us to authenticate your requests.

You can create a Web Services user using our MyST interface. Your system will need to submit this username in every request, along with the password. In our request examples we use a placeholder username and password, which you will need to replace with your own credentials before testing.

If you don’t already have Web Services credentials, click here to learn how to configure this.

You may need to open your firewall to our Web Services IPs.

Click here for a full list.

Your server will now need to generate a request. For example:

REQUEST

"sitereference": "test_site12345",
"requesttypedescriptions": ["AUTH"],
"accounttypedescription": "ECOM",
"currencyiso3a": "GBP",
"baseamount": "1050",
"orderreference": "My_Order_123",
"cachetoken": "<INSERT TOKEN HERE>"

We will accept any Unicode characters in your JSON request. The encoding used is UTF-8, which is a multi-byte encoding scheme. All responses from us are encoded using UTF-8. Your system must be prepared to accept any valid JSON responses encoded this way.

In order to meet strict security requirements we are unable to accept an origin of https://localhost when using our Cross-origin resource sharing (CORS) services.

You must use a valid domain that is accessible by Trust Payments.

You will need to submit the generated request to the Trust Payments library installed above.

The following are examples of how to perform a request for each tool and programming language we currently support.

PYTHON
PHP
CURL

#!/usr/bin/python
import securetrading
 
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
#Replace the example Web Services username and password above with your own
 
request = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "accounttypedescription": "ECOM",
  "currencyiso3a": "GBP",
  "baseamount": "1050",
  "orderreference": "My_Order_123",
  "cachetoken": "<INSERT TOKEN HERE>"
}
 
strequest = securetrading.Request()
strequest.update(request)
stresponse = st.process(strequest) #stresponse contains the transaction response

<?php
 
if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);
 
$configData = array(
  'username' => '[email protected]',
  'password' => 'Password1^',
);
//Replace the example Web Services username and password above with your own
 
$requestData = array(
  'sitereference' => 'test_site12345',
  'requesttypedescriptions' => array('AUTH'),
  'accounttypedescription' => 'ECOM',
  'currencyiso3a' => 'GBP',
  'baseamount' => '1050',
  'orderreference' => 'My_Order_123',
  'cachetoken' => '<INSERT TOKEN HERE>'
);
 
$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());
 
?>

curl --user [email protected]:Password1^ https://webservices.securetrading.net/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"[email protected]",
"version": "1.00",
  "request": [{
    "currencyiso3a": "GBP",
    "requesttypedescriptions": ["AUTH"],
    "sitereference": "test_site12345",
    "baseamount": "1050",
    "orderreference": "My_Order_123",
    "accounttypedescription": "ECOM",
    "cachetoken": "<INSERT TOKEN HERE>"
  }]
}'

For the purpose of these examples, we have hard-coded the request fields. In your implementation, you would need to have an automated process that updates each request before being submitted by the library.

Handling the response

Your system will be returned numerous fields in the response object. You will need to interpret the contents of these fields to ensure they are the values expected.

The following is an example of an AUTH response:

PYTHON
PHP
CURL

{
  u 'requestreference': u 'A0bxh87wt',
    u 'version': u '1.00',
    u 'response': [{
      u 'transactionstartedtimestamp': u '2016-12-07 11:32:44',
        u 'livestatus': u '0',
        u 'issuer': u 'SecureTrading Test Issuer1',
        u 'splitfinalnumber': u '1',
        u 'dccenabled': u '0',
        u 'settleduedate': u '2016-12-07',
        u 'errorcode': u '0',
        u 'orderreference': u 'My_Order_123',
        u 'tid': u '27882788',
        u 'merchantnumber': u '00000000',
        u 'merchantcountryiso2a': u 'GB',
        u 'transactionreference': u '23-9-80001',
        u 'merchantname': u 'Test Merchant',
        u 'paymenttypedescription': u 'VISA',
        u 'baseamount': u '1050',
        u 'accounttypedescription': u 'ECOM',
        u 'acquirerresponsecode': u '00',
        u 'requesttypedescription': u 'AUTH',
        u 'securityresponsesecuritycode': u '2',
        u 'currencyiso3a': u 'GBP',
        u 'authcode': u 'TEST36',
        u 'errormessage': u 'Ok',
        u 'operatorname': u '[email protected]',
        u 'securityresponsepostcode': u '0',
        u 'maskedpan': u '411111######0021',
        u 'securityresponseaddress': u '0',
        u 'issuercountryiso2a': u 'US',
        u 'settlestatus': u '0'
    }]
}

array(3) {
  ["requestreference"] => string(9) "A3579dkvx"
  ["version"] => string(4) "1.00"
  ["response"] => array(1) {
    [0] => array(28) {
      ["transactionstartedtimestamp"] => string(19) "2016-12-09 09:52:19"
      ["livestatus"] => string(1) "0"
      ["issuer"] => string(26) "SecureTrading Test Issuer1"
      ["splitfinalnumber"] => string(1) "1"
      ["dccenabled"] => string(1) "0"
      ["settleduedate"] => string(10) "2016-12-09"
      ["errorcode"] => string(1) "0"
      ["orderreference"] => string(12) "My_Order_123"
      ["tid"] => string(8) "27882788"
      ["merchantnumber"] => string(8) "00000000"
      ["securityresponsepostcode"] => string(1) "0"
      ["transactionreference"] => string(10) "72-9-80003"
      ["merchantname"] => string(13) "Test Merchant"
      ["paymenttypedescription"] => string(4) "VISA"
      ["baseamount"] => string(4) "1050"
      ["accounttypedescription"] => string(4) "ECOM"
      ["acquirerresponsecode"] => string(2) "00"
      ["requesttypedescription"] => string(4) "AUTH"
      ["securityresponsesecuritycode"] => string(1) "2"
      ["currencyiso3a"] => string(3) "GBP"
      ["authcode"] => string(6) "TEST31"
      ["errormessage"] => string(2) "Ok"
      ["operatorname"] => string(23) "[email protected]"
      ["merchantcountryiso2a"] => string(2) "GB"
      ["maskedpan"] => string(16) "411111######1111"
      ["securityresponseaddress"] => string(1) "0"
      ["issuercountryiso2a"] => string(2) "US"
      ["settlestatus"] => string(1) "0"
    }
  }
}

{"requestreference":"W23-fjgvn3d8","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 15:08:47","livestatus":"0","issuer":"SecureTrading Test Issuer1","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"1050","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"23-9-80006","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST96","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"zO9"}

It is especially important to check the Error Code and settle status values returned in the response.

In addition to processing authorisations, Trust Payments supports numerous other request types. For further information on these request types, please refer to the other pages within our online documents.

Summary

At this point, you should be able to process a basic request using our Webservices API.

Next steps

We recommend reading our Best practices in order to learn how to best handle the fields returned in the response.
You can refer to our additional documents to learn about other features that can be configured as part of your implementation.
Once you have tested your solution thoroughly, you can request to go live and begin to process live payments!

We’re here to help

We hope that you find our online help resource to be useful. If you are experiencing issues with your configuration, please visit our Troubleshooting page.