The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.
Read this article to learn more.
Features:
- Automate refunds and authorisation reversals, and control the settlement schedule for each transaction.
- Retain development capability and write applications that can process payments.
- Integrate a payment solution into back-office or legacy systems.
Install a library
To streamline the process of getting your payment solution up-and-running, we provide libraries for programming languages such as Python and PHP. 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 provided 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.
- 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.
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
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.
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 Portal 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.
Your server will now need to generate a request. For example:
"sitereference": "test_site12345",
"requesttypedescriptions": ["AUTH"],
"accounttypedescription": "ECOM",
"currencyiso3a": "GBP",
"baseamount": "1050",
"orderreference": "My_Order_123",
"pan": "4111111111111111",
"expirydate": "12/2022",
"securitycode": "123"
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.
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
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",
"pan": "4111111111111111",
"expirydate": "12/2022",
"securitycode": "123"
}
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' => 'webservices@example.com',
'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',
'pan' => '4111111111111111',
'expirydate' => '12/2022',
'securitycode' => '123'
);
$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());
?>
curl --user webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"webservices@example.com",
"version": "1.00",
"request": [{
"currencyiso3a": "GBP",
"requesttypedescriptions": ["AUTH"],
"sitereference": "test_site12345",
"baseamount": "1050",
"orderreference": "My_Order_123",
"accounttypedescription": "ECOM",
"pan": "4111111111111111",
"expirydate": "12/2022",
"securitycode": "123"
}]
}'
Replace <DOMAIN> with a supported domain. Click here for a full list.
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:
{
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 'webservices@example.com',
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) "webservices@example.com"
["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":"webservices@example.com","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.
Click here for recommended checks to perform when handling responses returned from Trust Payments.
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 about checks to perform when handling 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!
