1. No category

Web Services
This document covers how to process XML Requests and Responses
using the Secure Trading Web Services interface.
Version: 2.2
Published: 15 October 2014
Web Services
About this Document
This document covers how to process XML Requests and Responses using the Secure Trading
Web Services interface. XML specifications can be downloaded from Secure Trading’s website:
http://www.securetrading.com/support/document/category/web-services/
Conventions
Terminology conventions on “merchant” and “customer”
The supplier-customer chain within Secure Trading’s systems has two levels of customer,
Secure Trading therefore make a clear definition between the two:
Merchant relates to a customer of Secure Trading that uses the system to process
requests, such as those for online payments.
Customer relates to a customer of the merchant.
Naming conventions of XML through Secure Trading
Whenever a field used through Secure Trading’s systems is noted within this document, it will
be written in Courier font. If there is a large amount of code or XML to be included as an
example, then it will be included in a box such as the following.
<?xml version="1.0" encoding="utf-8"?>
<requestblock version="3.67">
…
</request>
</requestblock>
All fields that are processed through Secure Trading’s systems are lower case, and there is no
space or hyphen between words in order to avoid any confusion when programming. For
example, the field for submitting a field including a merchant’s Site Reference through the
system is called sitereference.
Note on bulleting conventions
There are two forms of bulleting conventions to be included within this document:
Notes with useful (but not mandatory) information for your consideration are
displayed in this manner.
Notes that are requirements, and need to be followed in order to prevent
future issues with your code, are indicated with an exclamation mark and
are outlined in bold, as shown here.
System Time
Secure Trading’s System Time is in Greenwich Mean Time (GMT).
© Secure Trading Limited 2014
15 October 2014
Page 2 / 15
Web Services
Table of Contents
1
Introduction ...................................................................................................................................... 4
1.1
1.2
2
Requirements ............................................................................................................................. 4
XML Requests and Responses ................................................................................................. 4
First-Time Configuration ................................................................................................................. 5
2.1
2.2
2.3
Create Web Services User......................................................................................................... 6
Submit XML Request to Secure Trading ................................................................................... 7
Listen for XML Response from Secure Trading ....................................................................... 10
3
Downloadable Java Example ........................................................................................................ 11
4
Connection Management .............................................................................................................. 12
4.1
4.2
4.3
5
Troubleshooting ............................................................................................................................. 14
5.1
5.2
6
SSL / HTTPS Authentication .................................................................................................... 12
DNS .......................................................................................................................................... 13
Timeouts................................................................................................................................... 13
401 Authorization Required...................................................................................................... 14
Windows Server 2003 .............................................................................................................. 14
Further Information and Support ................................................................................................. 15
6.1
6.2
6.3
6.4
Secure Trading Support ........................................................................................................... 15
Secure Trading Sales ............................................................................................................... 15
Useful Documents .................................................................................................................... 15
Frequently Asked Questions .................................................................................................... 15
© Secure Trading Limited 2014
15 October 2014
Page 3 / 15
Web Services
1
Introduction
Secure Trading Web Services is for merchants who want to use their own secure servers, but
wish to use Secure Trading’s payment network as part of their own ecommerce application. The
Web Services interface allows merchants to submit a request to Secure Trading using a client
program, providing a username and password for authentication. Web Services offers similar
functionality to the STAPI client interface, but does not require the STAPI Java client to be
installed on your server.
Using Secure Trading Web Services you can:
Automate refunds and authorisation reversals, and control the settlement schedule for
each transaction.
Have development capability and write applications that can process payments.
Integrate a payment solution into back-office or legacy systems.
1.1
Requirements
The pre-requisites that you will need to complete in order to begin processing payments through
Secure Trading Payment Platform (STPP) are outlined in this section of the document.
1.1.1
Internet Merchant Account
An Internet Merchant Account is required if you would like to process online e-commerce
transactions. Secure Trading have relationships in place with certain acquirers and will therefore
be able to assist you. For contact details of our sales team, please refer to section 6.2.
1.1.2
Secure Trading Account
In order to process transactions through Secure Trading’s servers, you will need to have an
account with us and a site reference. You are provided with a Secure Trading site reference
when you sign up and this is used to uniquely identify your account when you send any data to
Secure Trading. It should also be quoted in any correspondence with Secure Trading.
You will also be provided with a MyST username and password to allow you to perform certain
management tasks on your account.
For more information on becoming a Secure Trading merchant, please contact our Sales team
(see section 6.2). If you already have a Secure Trading account, but do not know your site
reference, please contact our support team (see section 6.1).
1.1.3
PCI Accreditation
When processing live transactions using Web Services, card details will be taken on your
servers, so you will need to ensure that you have your own secure server in place. You may
also therefore be required to undertake a form of PCI accreditation, which will differ depending
on the size of your company and the volume of transactions that are processed through your
system. For more information on PCI accreditation, please visit:
https://www.pcisecuritystandards.org
1.1.4
Secure Trading IP Ranges
You may need to open your firewall for Secure Trading’s IP Ranges.
Current IP Ranges can be viewed at http://webapp.securetrading.net/ips.html
1.2
XML Requests and Responses
Web Services sends XML Requests to Secure Trading and receives corresponding XML
Responses. The structure of the XML and the fields that can be submitted through STPP is
described in detail in the XML Specification document.
© Secure Trading Limited 2014
15 October 2014
Page 4 / 15
Web Services
2
First-Time Configuration
Follow these three steps to start making payments with Web Services:
STEP
1
Sign in to MyST and add a user with
role “Webservices” to your account.
See section 2.1 for further information.
STEP
2
Construct an XML Request and submit this to Secure Trading.
See section 2.2 for further information.
STEP
3
© Secure Trading Limited 2014

Listen for and interpret the XML
Response from Secure Trading.
See section 2.3 for further information.
15 October 2014
Page 5 / 15
Web Services
2.1
Create Web Services User
STEP
1
Sign in to MyST and add a user with role “Webservices” to your account.
1. Navigate to https://myst.securetrading.net/login. Sign in using your username & password.
2. Click “Add new username” from the left side-menu.
3. Fill in the fields shown (all required).
Ensure you select “Webservices” for the role.
Please note that Web Services usernames are email addresses that can have a
maximum length of 255 (maximum of 64 characters before the”@” symbol).
About the “Valid IP/network(s)” field (required)
By entering your system’s IP (or range of IPs) in
this field, Secure Trading will only accept Web
Services requests originating from this IP. This
means that even if your Web Services credentials
have been compromised, requests cannot be
performed without access to your IP network.
Multiple IP addresses can be separated with
either a semicolon (;) or a comma (,).
Ranges of IPs may be specified by using a
netmask in the format 1.2.3.4/8.
“Role if invalid IP” must be set to “Prevent login”.
4. Allocate the sites through which you wish to process Web Services payments.
5. Click “Save”.

Adding users is described in further detail in the MyST User Guide.
All Secure Trading documents can be found on our website.
© Secure Trading Limited 2014
15 October 2014
Page 6 / 15
Web Services
2.2
Submit XML Request to Secure Trading
STEP
2
Construct an XML Request and submit this to Secure Trading.
After configuring your Secure Trading account, you can submit XML Requests to the Web
Services interface by submitting an SSL POST request to:
https://webservices.securetrading.net:443/xml/
It is imperative that you read and understand the following sections of the
document, before submitting requests to Secure Trading using Web Services:


Section 4.1: SSL encryption and certificate authority information
Section 4.2: Secure Trading’s DNS load balancers
All Secure Trading Web Services Requests must be performed using HTTPS.
2.2.1
Headers
The HTTPS Requests sent to Secure Trading need to begin with a series of headers as defined
in this section of the document. These are used by Secure Trading to identify and manage
incoming requests.
A full example of a request including the XML and headers can be found in section 2.2.3.
The HTTPS headers must include the following:
Content-Type: text/xml;charset=utf-8
Content-Length: <LENGTH OF POST>
Accept: text/xml
Accept-Encoding: gzip
Authorization: <BASIC AUTH CREDENTIALS HERE>
User-Agent: <YOUR SOFTWARE VERSION HERE>
Host: webservices.securetrading.net
Connection: close
2.2.1.1 Content-Type
Content-Type will always be set as “text/xml”.
charset must be the charset of the post, for example “utf-8”.
2.2.1.2 Content-Length
Content-Length must be the length of the XML bytes in the chosen charset.
2.2.1.3 Accept
Accept will always be set as “text/xml”.
© Secure Trading Limited 2014
15 October 2014
Page 7 / 15
Web Services
2.2.1.4 Accept-Encoding
Accept-Encoding should be set as “gzip”.
This will compress the response, providing your client supports this functionality.
Please note that most Web Services clients will support gzip encoding.
Please check with your client software provider for further information.
2.2.1.5 Authorization
Basic access authentication is a method for a web browser client program to provide a
username and password when making a request.
You must include your username and password, separated by a colon and base64 encoded in
the authorisation header when performing the request.
For example:
Username: [email protected]
Password: pa55word
Separated by a colon: [email protected]:pa55word
Base64 encode: d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=
Therefore, for the example above, the HTTPS header should include:
Authorization: Basic d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=
2.2.1.6 User-Agent
User-Agent will contain the name/version of your system’s application software.
e.g.
Mozilla/5.0 (X11; U; Linux i686; en-US; rv:1.8.1.11) Gecko/20071204
Ubuntu/7.10 (gutsy) Firefox/2.0.0.11
2.2.1.7 Host
Host will always be set as “webservices.securetrading.net”.
2.2.1.8 Connection
Connection should be set to “close”. This ensures each request uses a new SSL
connection.
2.2.2
XML
The headers are followed by XML that instructs STPP (Secure Trading Payment Platform) to
perform certain actions (e.g. seek authorisation for a transaction).
Full XML examples can be found in:
The XML Specification document and other XML documentation on Secure Trading’s
website.
The downloadable directory of XML examples, hosted by Secure Trading:
http://webapp.securetrading.net/examples/WEBSERVICES.zip
© Secure Trading Limited 2014
15 October 2014
Page 8 / 15
Web Services
2.2.3
Example of HTTPS Request to Secure Trading
The following is an example of a complete HTTPS request, including the headers described in
section 2.2.1 and XML outlined in section 2.2.2, using the site reference “test_site12345”, with
the username “[email protected]” and password “password”.
POST /xml/ HTTP/1.0
Content-Type: text/xml;charset=utf-8
Content-Length: 839
Accept: text/xml
Accept-Encoding: gzip
Authorization: <BASIC AUTH CREDENTIALS HERE>
User-Agent: <YOUR SOFTWARE VERSION HERE>
Host: webservices.securetrading.net
Connection: close
<requestblock version="3.67">
<alias>[email protected]</alias>
<request type="AUTH">
<operation>
<sitereference>test_site12345</sitereference>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
<merchant>
<orderreference>Example AUTH</orderreference>
<termurl>https://www.example.com/termurl.cgi</termurl>
<name>Test Merchant</name>
</merchant>
<customer>
<ip>1.2.3.4</ip>
</customer>
<billing>
<amount currencycode="GBP">2115</amount>
<town>Bangor</town>
<country>GB</country>
<payment type="VISA">
<expirydate>10/2031</expirydate>
<pan>4111111111111111</pan>
<securitycode>123</securitycode>
</payment>
</billing>
<settlement/>
</request>
</requestblock>
Please note for the XML Requests processed using Web Services, the <alias>
tag will be your Web Services username.

The structure of XML Requests to be sent to Secure Trading is described in the
XML Specification document
All Secure Trading documents can be found on our website.
© Secure Trading Limited 2014
15 October 2014
Page 9 / 15
Web Services
2.3
Listen for XML Response from Secure Trading
STEP
3
Listen for and interpret the XML Response from Secure Trading.
Secure Trading will respond to all valid requests it receives from merchants. The following is an
example of an XML Response sent by Secure Trading (encoded in UTF-8 character encoding):
<?xml version='1.0' encoding='utf-8'?>
<responseblock version="3.67">
<requestreference>X3148177</requestreference>
<response type="AUTH">
<merchant>
<merchantname>Test Merchant</merchantname>
<orderreference>Example AUTH</orderreference>
<tid>27880001</tid>
<merchantnumber>00000000</merchantnumber>
<merchantcountryiso2a>GB</merchantcountryiso2a>
</merchant>
<transactionreference>4-9-1533116</transactionreference>
<timestamp>2014-05-20 09:47:17</timestamp>
<acquirerresponsecode>00</acquirerresponsecode>
<operation>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
<settlement>
<settleduedate>2014-05-20</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<billing>
<amount currencycode="GBP">2115</amount>
<payment type="VISA">
<issuer>SecureTrading Test Issuer1</issuer>
<pan>411111######1111</pan>
<issuercountry>US</issuercountry>
</payment>
<dcc enabled="0"/>
</billing>
<authcode>TEST</authcode>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<security>
<postcode>0</postcode>
<securitycode>2</securitycode>
<address>0</address>
</security>
</response>
</responseblock>
You will need to analyze the different fields returned in the response to determine whether or
not the request was successful (in particular the <error> <code> and <settlestatus>
elements). Information on how best to check the XML Response can be found in the Best
Practices section of the XML Specification document.
© Secure Trading Limited 2014
15 October 2014
Page 10 / 15
Web Services
3
Downloadable Java Example
To demonstrate how Web Services can be implemented on your system, an example of Java
code can be downloaded, which submits an XML Request to Secure Trading and listens for and
displays the XML Response:
http://webapp.securetrading.net/examples/WEBSERVICES/Post.java
This code takes a file containing a valid XML Request, applies the headers as described in
section 2.2.1 and securely submits it to Secure Trading. The full XML Response is displayed in
a terminal window.
Before executing the code, you will need to amend the Java code as to include your Web
Services credentials:
Change the static String username to be the username of your Web Services user.
Change the static String password to be the password of your Web Services user.
Ensure the static String requestXML contains the path of the file containing the XML
Request you wish to submit to Secure Trading.
Please note that the example Java code provided by Secure Trading applies the
headers to the XML Request before sending. The file specified in the requestXML
String will only work if it contains the XML Request without the headers.
After compiling the code, you can execute it in order to submit the XML Request to Secure
Trading. The XML Response will be printed into a terminal window (see section 2.3).
Please note that the example Java code provided by Secure Trading does not
take load balancing into account. Please ensure your system follows the
guidelines outlined in section 4.2.
This example code is provided for demonstration purposes and it is
expected that all merchants develop their own solution.
© Secure Trading Limited 2014
15 October 2014
Page 11 / 15
Web Services
4
Connection Management
4.1
SSL / HTTPS Authentication
It is imperative that any connections between your server and Secure Trading Web Services
are properly authenticated and encrypted.
Secure Trading use industry standard high-strength SSL/TLS encryption. We recommend
that you use an up-to-date SSL library implementation for your chosen language.
You should ensure it has the following capabilities:
SSLv3/TLSv1.0 or higher capabilities.
Server authentication must be performed by validating a certificate chain up to a known,
trusted Certificate Authority (see below).
Server authentication must check the Common Name (CN) of the server certificate
matches the domain to which you are connecting. If the Common Name does not
match, you are not connected to Secure Trading and the connection MUST be rejected.
Server authentication must be performed on the expiry date of the server certificate.
Any expired certificates MUST be rejected.
It is imperative that you check all SSL certificates against an up to date certificate
revocation list (CRL).
Secure Trading use the Verisign Certificate Authority to sign our certificates. Your SSL library
must be configured to trust all Verisign certificates: http://www.verisign.com/support/roots.html
Your SSL policy should include reviewing and updating these Certificate Authorities on a
regular basis (e.g. once a year).
Validating a chain to a trusted Certificate Authority means your implementation will not need
any changes when Secure Trading regularly update server certificates. In particular you
should NOT verify using a single certificate fingerprint, as this will require updating whenever
the server certificate is updated and will not work if our distributed system provides
different individual certificates. (More information on Certificate Authorities can be found at
http://en.wikipedia.org/wiki/Root_certificate although this should not be necessary to
integrate with Secure Trading Web Services).
Most SSL library implementations will fulfil all the above requirements but
may need to be configured to enable them. It is your responsibility to
ensure that all such security requirements are correctly enabled; otherwise
the security of the connections may be compromised. It is also your
responsibility to ensure the operating system and software used for
connections is kept up to date with security patches.
If you are in any doubt of the ability of your application to perform all of the
aforementioned DNS and SSL requirements, Secure Trading recommends
you instead use the STAPI client, which fulfils all these requirements.
© Secure Trading Limited 2014
15 October 2014
Page 12 / 15
Web Services
4.2
DNS
Secure Trading employs DNS load balancing. DNS load balancing is designed to return a single
IP, which will be the preferred destination for your server to connect to at that moment in time.
In addition to returning a single IP, the DNS load balancers will return a low TTL, currently set to
less than 60 seconds. This TTL has been deliberately kept low in order to maximize your
server’s exposure to the entire payment system. Increasing this TTL would reduce this
exposure, meaning you will utilise one IP for a prolonged period of time. Any issues that could
occur (scheduled or otherwise) will then impact on your payment processing capabilities.
It is imperative that you adhere to the TTL set by Secure Trading and refresh
your DNS entries when the TTL expires and connect to the newly returned
IP.
Secure Trading have a number of DNS servers used to serve DNS records. It is important that
your server includes all of these servers for DNS lookups. If you receive a DNS look up failure
when communicating with a DNS server, the other DNS servers must then be used. Failure to
utilise all DNS servers may cause DNS problems when trying to resolve payment system URLs.
It is recommended to include DNS lookups to securetrading.net in your
application to continuously obtain the current list of DNS servers available.
From a debug perspective, you can execute the following command:
Windows: nslookup -type=NS securetrading.net
Linux: dig NS securetrading.net
4.3
Timeouts
In the unlikely event that your system encounters problems when connecting to Secure Trading,
it is recommended that you implement appropriate timeouts for your solution. Consider this
example:
maximum retry number – 20
maximum retry timeout – 40 seconds
maximum connect attempt timeout – 5 seconds
send and receive timeout – 60 seconds
Retry until:
The maximum retry number is exceeded; OR
The maximum retry timeout would be exceeded by another connection attempt.
(This means stop retrying the connection after 35-40 seconds, as an attempt that takes
the maximum connect attempt timeout of 5 seconds would cause the maximum retry
timeout to be exceeded)
Once the connection is established, allow 60 seconds (the send and receive timeout value) to
send and receive the data before closing the connection. If for any reason the connection
terminates after data has started to be transferred, we do not recommend retrying the request.
The timeout implementation suggested above is an example solution. You will
need to consider the requirements of your own application and implement
timeouts that best suit your needs.
© Secure Trading Limited 2014
15 October 2014
Page 13 / 15
Web Services
5
Troubleshooting
5.1
401 Authorization Required
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 2.0//EN">
<html><head>
<title>401 Authorization Required</title>
</head><body>
<h1>Authorization Required</h1>
<p>This server could not verify that you
are authorized to access the document
requested. Either you supplied the wrong
credentials (e.g., bad password), or your
browser doesn't understand how to supply
the credentials required.</p>
</body></html>
5.1.1
Invalid Username / Password
Please ensure you have submitted your Web Services username and password correctly in the
request to Secure Trading.
5.1.2
Restrictions based on IP Range
Restrictions can be put in place to ensure that only Web Services Requests originating from
your IP (or range of IPs) are accepted by Secure Trading. This error is returned when Secure
Trading receives a request originating from an IP outside of this range, which is first defined
when creating the “Webservices” user in MyST (described in section 2.1).
It is possible to modify the range of IPs accepted by Secure Trading by modifying the
“Webservices” user in MyST. For more information on modifying users, please refer to the
MyST User Guide.
5.2
Windows Server 2003
In 2013, the signature algorithm used in our certificates was changed from using
SHA-1 (160 bit) to SHA-2 (256 bit), in the interest of security. These changes to our
certificates have affected older servers. Merchants/developers using Windows
Server 2003, who have encountered problems with their Web Services
implementation, will require the following software patch from Microsoft:
http://support.microsoft.com/kb/968730?wa=wsignin1.0
© Secure Trading Limited 2014
15 October 2014
Page 14 / 15
Web Services
6
Further Information and Support
This section provides useful information with regards to documentation and support for your
Secure Trading solution.
6.1
Secure Trading Support
If you have any questions regarding integration or maintenance of the system, please contact
our support team using one of the following methods.
Method
Telephone
Fax
Email
Website
6.2
Details
+44 (0) 1248 672 050
+44 (0) 1248 672 099
[email protected]
http://www.securetrading.com/support/support.html
Secure Trading Sales
If you do not have an account with Secure Trading, please contact our Sales team and they will
inform you of the benefits of a Secure Trading account.
Method
Telephone
Telephone (Int’l)
Fax
Email
Website
6.3
Details
0800 028 9151
+44 (0) 1248 672 070
+44 (0) 1248 672 079
[email protected]
http://www.securetrading.com
Useful Documents
Any document regarding STPP can be found on Secure Trading’s website:
http://www.securetrading.com/
6.4
Frequently Asked Questions
Please visit the FAQ section on our website (http://www.securetrading.com/support/faq).
© Secure Trading Limited 2014
15 October 2014
Page 15 / 15