This document covers how to process XML Requests and Responses using the Secure Trading Web Services interface. Published: 28 March 2018 3.8 (a)
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... 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 Secure Trading Limited 2018 28 March 2018 Page 2 / 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: 1.1 Required steps 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. 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.1 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. Secure Trading Limited 2018 28 March 2018 Page 3 / 17
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. Secure Trading Limited 2018 28 March 2018 Page 4 / 17
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. Please note that Web Services usernames are email addresses that can have a maximum length of 255 (maximum of 64 characters before the @ symbol). 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. Role if invalid IP must be set to Prevent login. 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. Secure Trading Limited 2018 28 March 2018 Page 5 / 17
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. Secure Trading Limited 2018 28 March 2018 Page 6 / 17
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 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 2018 28 March 2018 Page 7 / 17
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. 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. Secure Trading Limited 2018 28 March 2018 Page 8 / 17
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: webservices@example.com Password: pa55word Separated by a colon: webservices@example.com:pa55word Base64 encode: d2vic2vydmljzxnazxhhbxbszs5jb206cge1nxdvcmq= Base64 encode and decode example The following is an example in Python to encode webservices@example.com:pa55word in base64. Some languages support base64 natively, however you may need to use a third-party encoder. import base64 encoded = base64.b64encode('webservices@example.com:pa55word') print encoded #'d2vic2vydmljzxnazxhhbxbszs5jb206cge1nxdvcmq=' decoded = base64.b64decode('d2vic2vydmljzxnazxhhbxbszs5jb206cge1nxdvcmq=') print decoded #'webservices@example.com:pa55word' Once encoded, you would pass the encoded string in the HTTPS header, as follows: Authorization: Basic d2vic2vydmljzxnazxhhbxbszs5jb206cge1nxdvcmq= Secure Trading Limited 2018 28 March 2018 Page 9 / 17
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 Secure Trading Limited 2018 28 March 2018 Page 10 / 17
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 webservices@securetrading.com 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>webservices@securetrading.com</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. Secure Trading Limited 2018 28 March 2018 Page 11 / 17
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. Secure Trading Limited 2018 28 March 2018 Page 12 / 17
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. Secure Trading Limited 2018 28 March 2018 Page 13 / 17
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. Secure Trading Limited 2018 28 March 2018 Page 14 / 17
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 support@securetrading.com with your site reference and request to go live. You will receive a response when your live site is ready to begin processing payments. Secure Trading Limited 2018 28 March 2018 Page 15 / 17
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 support@securetrading.com 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 sales@securetrading.com 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). Secure Trading Limited 2018 28 March 2018 Page 16 / 17
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. Secure Trading Limited 2018 28 March 2018 Page 17 / 17