STPP Web Services

3.12

Web Services User Guide

This document covers how to process XML Requests and Responses using the Secure Trading Web Services interface. Published: 6 November 2018


© Secure Trading Limited 2018 6 November 2018 Page 2 / 17

Table of Contents

1 Introduction ...................................................................................................................................... 3

1.1 Required steps ........................................................................................................................... 3

2 Pre-Requisites .................................................................................................................................. 4

2.1 Internet Merchant Account ......................................................................................................... 4 2.2 Secure Trading Account ............................................................................................................. 4 2.3 PCI Accreditation ....................................................................................................................... 4

3 MyST Configuration ......................................................................................................................... 5

4 Configure your server ...................................................................................................................... 6

4.1 Firewall ....................................................................................................................................... 6 4.2 Secure Connection ..................................................................................................................... 6 4.3 Load Balancing .......................................................................................................................... 7 4.4 Timeouts and other connection problems .................................................................................. 7

5 XML Code .......................................................................................................................................... 8

5.1 Construct XML Request ............................................................................................................. 8 5.2 Listen for XML Response from Secure Trading ....................................................................... 12

6 Testing ............................................................................................................................................. 13

6.1 Test site reference ................................................................................................................... 13 6.2 Sending a request .................................................................................................................... 13

7 Troubleshooting ............................................................................................................................. 14

7.1 401 Authorization Required...................................................................................................... 14 7.2 Malformed XML error (‘10200’) ................................................................................................ 14

8 Going Live ....................................................................................................................................... 15

8.1 Notifications and Redirects for Live Site Reference ................................................................ 15 8.2 Update your XML Requests ..................................................................................................... 15 8.3 Contact Secure Trading ........................................................................................................... 15

9 Further Information and Support ................................................................................................. 16

9.1 Secure Trading Support ........................................................................................................... 16 9.2 Secure Trading Sales ............................................................................................................... 16 9.3 Useful Documents .................................................................................................................... 16 9.4 Frequently Asked Questions .................................................................................................... 16

10 Appendix ..................................................................................................................................... 17

10.1 Downloadable Java Example ................................................................................................... 17



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 Required steps

Before you can begin processing live transactions using Web Services, please complete the steps listed below. These are to ensure requests are sent securely and reliably: (You can begin testing before these steps are completed.)

Obtain Internet merchant account See section 2.1

Sign up for Secure Trading account See section 2.2

Ensure you are PCI accredited when handling card details on your servers See section 2.3

Register Web Services user on MyST See section 3

Open your firewall for Secure Trading’s IP ranges See section 4.1

Use SSL for connections and check certificates against up-to-date CRL See section 4.2

Configure your system to work with Secure Trading’s load-balancer See section 4.3

Implement timeouts handling See section 4.4

Construct an XML Request See section 5

Listen for an XML Response See section 5.2

Perform test transactions See section 6

Go live See section 8

To demonstrate how Web Services can be implemented on your system, a Java code example can be downloaded, which submits an XML Request to Secure Trading and listens for and displays the XML Response. See section 10.1.



2 Pre-Requisites

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.

2.1 Internet Merchant Account

An Internet Merchant Account is required if you would like to process online 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 9.2.

2.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 two Secure Trading site references when you sign up (one for live transactions and another for test purposes) and these are used to uniquely identify your account when you submit any data to Secure Trading. It should also be quoted in any correspondence with Secure Trading. Site references consist of an alphanumeric string (usually including your company name) which is unique to your account. When referencing a site reference, you will need to be aware it is case sensitive. 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 9.2). If you already have a Secure Trading account, but do not know your site reference, please contact our support team (see section 9.1).

If you do need to contact Secure Trading support, please be aware that for security reasons we may only speak to an authorised contact of the account.

2.3 PCI Accreditation

When card details are handled on your servers, you will 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 by your system. For more information on PCI accreditation, please visit: https://www.pcisecuritystandards.org

Care must be taken to ensure that sensitive information remains secure on your server. It is recommended that you do not store credit card details on your server.

https://www.pcisecuritystandards.org/



3 MyST Configuration

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

“Valid IP/network(s)” field In the interest of security, you are required to enter 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.

4. Allocate the sites through which you wish to process Web Services payments, by clicking the

green arrows next to the corresponding sites and ensuring they move from the “Available” column to the “Allocated” column.

5. Click “Save”. Adding users is described in further detail in the MyST User Guide.

“Role if invalid IP” must be set to “Prevent login”.

https://myst.securetrading.net/login

http://www.securetrading.com/wp-content/uploads/2013/07/STPP-My-ST-User-Guide.pdf



4 Configure your server

4.1 Firewall

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

4.2 Secure Connection

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 TLS encryption. We recommend that you use an up-to-date SSL/TLS library implementation for your chosen language. You should ensure it has the following capabilities:

TLSv1.0 or higher capabilities (use TLSv1.1 or TLSv1.2 if available). 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). Your library and code base must be maintained and you must regularly update to the

latest security patches and/or features.

Secure Trading uses the Verisign Certificate Authority to sign all certificates. Your SSL/TLS library must be configured to trust all Verisign certificates: http://www.verisign.com/support/roots.html Your SSL/TLS 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 updates 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/TLS 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/TLS requirements, Secure Trading recommends you instead use the STAPI client, which fulfils all these requirements.

http://webapp.securetrading.net/ips.html

http://www.verisign.com/support/roots.html

http://en.wikipedia.org/wiki/Root_certificate

http://www.securetrading.com/sites/default/files/downloads/stapi/STPP%20STAPI%20User%20Guide.pdf



4.3 Load Balancing

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 has 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 to obtain the current list of DNS servers available:

Windows: nslookup -type=NS securetrading.net Linux: dig NS securetrading.net

4.4 Timeouts and other connection problems

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.



5 XML Code

5.1 Construct XML Request

After configuring your Secure Trading account and your server, you can submit XML Requests to the Web Services interface by submitting an SSL POST request to: https://webservices.securetrading.net:443/xml/

All Secure Trading Web Services Requests must be performed using HTTPS. See section 4.2.

To demonstrate how Web Services can be implemented on your system, a Java code example can be downloaded, which submits an XML Request to Secure Trading and listens for and displays the XML Response. See section 10.1.

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

5.1.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”.

Any request must be correctly encoded according to the character encoding specified in the XML header, as shown in the example above. The STPP system will accept any Unicode characters. The default encoding used for XML is UTF-8 which is a multi-byte encoding scheme. Most XML parsers will automatically handle this.



5.1.1.2 Content-Length

Content-Length must be the length of the XML bytes in the chosen charset. This must be

calculated after any character encoding has been performed.

5.1.1.3 Accept

Accept will always be set as “text/xml”.

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

The response will be encoded with gzip and your client will need to decode this.

Please check with your client software provider for further information.

5.1.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=

Base64 encode and decode example

The following is an example in Python to encode “[email protected]:pa55word” in base64. Some languages support base64 natively, however you may need to use a third-party encoder. import base64

encoded = base64.b64encode('[email protected]:pa55word')

print encoded

#'d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ='

decoded =

base64.b64decode('d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=')

print decoded

#'[email protected]:pa55word'

Once encoded, you would pass the encoded string in the HTTPS header, as follows: Authorization: Basic d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=



5.1.1.6 User-Agent

User-Agent will contain the name/version of your system’s application software.

E.g. A web browser’s user agent will look similar to the following: 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

5.1.1.7 Host

Host will always be set as “webservices.securetrading.net”.

5.1.1.8 Connection

Connection must be set to “close”. This ensures requests continue successfully during

maintenance windows. The setting “keep-alive” is not supported by this service.

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

http://www.securetrading.com/sites/default/files/downloads/xml/STPP%20XML%20Specification.pdf

http://webapp.securetrading.net/examples/WEBSERVICES.zip



5.1.3 Example of HTTPS Request to Secure Trading

The following is an example of a complete HTTPS request, including the headers described in section 5.1.1 and XML outlined in section 5.1.2, using the site reference “test_site12345”, with the username “[email protected]” and password “password”.

Please note for the XML Requests processed using Web Services, the <alias>

tag will be your Web Services username.

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>

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.


http://www.securetrading.com/support/



5.2 Listen for 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.

All responses from Secure Trading are encoded using UTF-8. Your system must be prepared to accept any valid XML encoded this way (even if the request uses a different encoding). Most XML parsers will handle this automatically as it is part of the XML Specification.




6 Testing

6.1 Test site reference

You will be provided with a “test” site reference and a “live” site reference on sign up. All test site references are preceded with the word “test_” (e.g. “test_merchant12345”). Secure Trading recommends you test your solution thoroughly before processing live transactions. Your test site references will always be available for you to process test transactions, even after going live.

6.2 Sending a request

To perform a successful test transaction, you will need to submit a valid XML Request to Secure Trading, by following the instructions outlined previously in this document, ensuring you include the name of your test site reference. Full XML examples and definitions of all commonly used fields can be found in the XML Specification document. In particular, please refer to the testing section of this document for valid card numbers and address details that can be submitted to test for different responses.

http://www.securetrading.com/files/documentation/STPP-XML-Specification.pdf



7 Troubleshooting

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

7.1.1 Invalid Username / Password

Please ensure you have submitted your Web Services username and password correctly in the request to Secure Trading.

7.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 3). 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.

7.2 Malformed XML error (‘10200’)

<?xml version='1.0' encoding='utf-8'?>

<responseblock version="3.67">

<requestreference>W1-234abcd</requestreference>

<response type="ERROR">

<timestamp>2015-12-18 10:29:23</timestamp>

<error>

<message>Malformed XML</message>

<code>10200</code>

<data>expected '>', line 61, column 25</data>

</error>

</response>

</responseblock>

7.2.1 Check your XML is valid

Ensure any opening tags have an associated closing tag. Ensure your XML doesn’t include invalid special characters for your chosen encoding. Ensure all tags are lowercase. e.g. Always use <billing> and not <Billing> or <BILLING>

7.2.2 Check your Content-Length

This kind of error can occur when the Content-Length header is calculated before encoding the XML. The Content-Length header must contain the number of bytes in the actual payload of the request and therefore must be calculated after any character encoding is performed.





8 Going Live

In the interest of security and redundancy, you MUST address all of the steps listed in section 1.1 before going live.

8.1 Notifications and Redirects for Live Site Reference

When you are ready to switch your account live, you will need to consider any notifications that may have been configured on your test site reference, as these will need to be re-configured on your live site reference to ensure they update your system as expected.

8.2 Update your XML Requests

You will need to ensure the XML Requests are using your live site reference in the <sitereference> field.

8.3 Contact Secure Trading

Once you have tested your system and you are ready to go live, please send an email to [email protected] with your site reference and request to go live. You will receive a response when your live site is ready to begin processing payments.

mailto:[email protected]



9 Further Information and Support

This section provides useful information with regards to documentation and support for your Secure Trading solution.

9.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 Details

Telephone +44 (0) 1248 672 050

Fax +44 (0) 1248 672 099

Email [email protected]

Website http://www.securetrading.com/support/support.html

9.2 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 Details

Telephone 0800 028 9151

Telephone (Int’l) +44 (0) 1248 672 070

Fax +44 (0) 1248 672 079

Email [email protected]

Website http://www.securetrading.com

9.3 Useful Documents

Any document regarding STPP can be found on Secure Trading’s website: http://www.securetrading.com/

9.4 Frequently Asked Questions

Please visit the FAQ section on our website (http://www.securetrading.com/support/faq).


http://www.securetrading.com/support/support.html


http://www.securetrading.com/

http://www.securetrading.com/

http://www.securetrading.com/support/faq



10 Appendix

10.1 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 5.1.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 5.2).

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.3. This example code is provided for demonstration purposes and it is expected that all merchants develop their own solution.

http://webapp.securetrading.net/examples/WEBSERVICES/Post.java