Contents

Processing payments

The following describes how you can reference the SDK functions within your program body to submit a request to our servers. We also provide additional information for those looking to submit the requests using their own library.

 

Envelope
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. The username must be a valid email address. 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.

Info
You may need to open your firewall to our Web Services IPs:
194.74.4.78 and 195.224.56.78

 

By this stage, the cachetoken generated in step 2 should have been posted to your server by the payment form, along with any additional fields (e.g. billing address).

Your server will need to generate a request comprised of this cachetoken and additional field data.
For example:


    "sitereference": "test_site12345",
    "requesttypedescriptions": ["AUTH"],
    "accounttypedescription": "ECOM",
    "currencyiso3a": "GBP",
    "baseamount": "1050",
    "orderreference": "My_Order_123",
    "cachetoken": "token_posted_by_st.js"

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

 

Processing a request using a Secure Trading library

You will need to submit the generated request to the Secure Trading library installed in step 1.

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


#!/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": "token_posted_by_st.js"
}

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' => 'token_posted_by_st.js'
);

$api = Securetradingapi($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": "token_posted_by_st.js"
  }]
}'

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

 

Processing a request using your own library

Your library will need to establish a secure connection to https://webservices.securetrading.net/json/
For further information on how to establish a secure connection, please refer to our “Configuring your own library” page. This page also covers the information you will need to implement appropriate timeouts for your solution, in case of unexpected connection issues.

In addition, you will need to send the request string and headers as shown in the example below:


{
"alias": "[email protected]",
"version": "1.00",
  "request": [{
    "currencyiso3a": "GBP",
    "requesttypedescriptions": ["AUTH"],
    "sitereference": "test_site12345",
    "baseamount": "1050",
    "orderreference": "My_Order_123",
    "accounttypedescription": "ECOM",
    "cachetoken": "token_posted_by_st.js"
  }]
}
{
   'Content-length': '363',
   'Content-type': 'application/json', 
   'Authorization': 'Basic d2Vic2VydmljZXNAZXhhbXBsZS5jb206UGFzc3dvcmQxXg==', 
   'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8'
}


‘Authorization’: ‘Basic d2Vic2VydmljZXNAZXhhbXBsZS5jb206UGFzc3dvcmQxXg==’

 

‘Basic ‘, followed by a base64 encoding of your Web Services username:password, stripped of whitespace characters.

 

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:


{
  u 'requestreference': u 'A0bxh87wt',
    u 'version': u '1.00',
    u 'responses': [{
      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"
  ["responses"] => 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.

Warning
Cachetokens expire 15 minutes after being generated
Payments attempted after 15 minutes will return a “20030” errorcode in the response (Missing token).

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

 


 

Status good

Summary

At this point, you should be able to process a basic payment using the information provided in the “Getting started” section.

 

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!

 

Life ring

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.