ST2K to STPP XML Migration Guide
Document which details the steps to migrate from ST2K to STPP.
Version: 1.0
Published: 9 October 2014
ST2K to STPP XML Migration Guide
1
Introduction
If you currently utilise an XPay / XPay4 setup on the legacy ST2K platform, upgrading to STPP
would provide the following benefits:
You will no longer be required to host a Java API client on your system.
You will no longer be required to maintain legacy version of Java.
You will no longer have to utilise any certificate files.
To migrate to our Webservices platform from an XPay solution, there are a few key aspects to
consider:
The XML has a different structure. The differences are outlined in this document.
Webservices utilises an SSL POST rather than an installed API client.
Webservices uses Username and Password (Basic) authentication instead of
certificates.
Connection management
(explained in the Connection Management section of the Web Services User Guide).
This document aims to address these points to ensure the migration process is easy to
understand and implement.
1.1
About STAPI
An alternative to using Web Services is to install the Secure Trading API (STAPI) java client on
your server, which handles the connection management automatically. This is used to send
XML Requests and to listen for XML Responses, using a certificate signed by Secure Trading
for authentication.
For information on how to configure the STAPI client, please refer to the STAPI User Guide:
http://www.securetrading.com/sites/default/files/downloads/stapi/STPP%20STAPI%20Us
er%20Guide.pdf
2
Web Services account
Before your system can begin to submit XML Requests to STPP, you will need to sign in to
MyST and register a new user with “Webservices” role, by clicking “Add new username” from
the left side-menu and filling out the form presented on-screen. If you need assistance, please
contact Secure Trading Support ([email protected]).
Remember the username and password. You will need this when constructing the XML header,
as described later in this document.
© Secure Trading Limited 2014
9 October 2014
Page 2 / 9
ST2K to STPP XML Migration Guide
3
XML Request
Your SSL POST with the constructed XML request should be submitted to:
https://webservices.securetrading.net:443/xml/
3.1
Encoding and version
Please note the following differences to the encoding and version number:
XPay / Xpay4
<?xml version="1.0" encoding="iso-8859-1"?>
<RequestBlock Version=“3.51”>
Webservices
The STPP system will accept any Unicode characters. The default encoding used for XML is
utf-8, which is a multi-byte encoding scheme (iso-8859-1 also supported).
Be aware that all XML Responses are always encoded in 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.
<?xml version="1.0" encoding="utf-8"?>
<requestblock version="3.67">
3.2
Alias
On the STPP platform, there is a new tag which will contain your Webservices username,
known as the “Alias”:
<alias>[email protected]</alias>
3.3
Order reference
The order reference, previously in the <order> tag, is now submitted in the <merchant> tag.
XPay / Xpay4
<Order>
<OrderReference>Order0001</OrderReference>
<OrderInformation>Test Order</OrderInformation>
</Order>
Webservices
<merchant>
<orderreference>REF12345</orderreference>
</merchant>
© Secure Trading Limited 2014
9 October 2014
Page 3 / 9
ST2K to STPP XML Migration Guide
3.4
Customer information
Please note the following differences to the submission of customer information. In particular,
note that the <CustomerInfo> tag is now called <customer>.
Unlike ST2K, on the new STPP platform, two addresses can be submitted in a
payment request. The customer’s delivery address can be included in the
<customer> tag. The customer’s billing address can be included in the
<billing> tag.
XPay / Xpay4
<CustomerInfo>
<Postal>
<Name>
<NamePrefix>Mr.</NamePrefix>
<FirstName>Joe</FirstName>
<MiddleName>A.</MiddleName>
<LastName>Bloggs</LastName>
<NameSuffix>CEng.</NameSuffix>
</Name>
<Company>A COMPANY</Company>
<Street>A STREET</Street>
<City>A CITY</City>
<StateProv>A STATE</StateProv>
<PostalCode>TE2 3ST</PostalCode>
<CountryCode>GBR</CountryCode>
</Postal>
<Telecom>
<Phone>0000 111111</Phone>
</Telecom>
<Online>
<Email>[email protected]</Email>
</Online>
</CustomerInfo>
Webservices
<customer>
<town>Bangor</town>
<name>
<middle>Mary</middle>
<prefix>Miss</prefix>
<last>Smith</last>
<first>Joanne</first>
</name>
<ip>1.2.3.4</ip>
<telephone type="H">1111111111</telephone>
<street>Second Street</street>
<postcode>CU888ST</postcode>
<premise>111</premise>
</customer>
© Secure Trading Limited 2014
9 October 2014
Page 4 / 9
ST2K to STPP XML Migration Guide
3.5
Billing information
Please note the following differences to the submission of billing information.
XPay / Xpay4
<PaymentMethod>
<CreditCard>
<Type>VISA</Type>
<Number>4111111111111111</Number>
<Issue></Issue>
<StartDate></StartDate>
<ExpiryDate>02/05</ExpiryDate>
<SecurityCode>246</SecurityCode>
</CreditCard>
</PaymentMethod>
Webservices
<billing>
<telephone type="M">0777777777</telephone>
<county>Gwynedd</county>
<street>Test Street</street>
<postcode>TE45 6ST</postcode>
<premise>789</premise>
<payment type="VISA">
<expirydate>10/2031</expirydate>
<pan>4111110000000211</pan>
<securitycode>123</securitycode>
</payment>
<town>Bangor</town>
<name>
<middle>joe</middle>
<prefix>Dr</prefix>
<last>bloggs</last>
<suffix>Jr.</suffix>
<first>fred</first>
</name>
<country>GB</country>
<amount currencycode="GBP">100</amount>
<email>[email protected]</email>
</billing>
3.6
Site reference
Where the legacy ST2K platform was expecting a reference to your certificate (which is no
longer required), your system will need to submit your site reference in the <operation> tag.
Please refer to the example, below:
Webservices
<operation>
<sitereference>site12345</sitereference>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
</request>
</requestblock>
© Secure Trading Limited 2014
9 October 2014
Page 5 / 9
ST2K to STPP XML Migration Guide
This section has provided a brief overview of the most important changes to the XML when
migrating from the legacy ST2K platform to STPP, but for more in-depth information, please
refer to the XML Specification:
http://www.securetrading.com/files/documentation/STPP-XML-Specification.pdf
And for pre-built example XML files, see:
http://webapp.securetrading.net/examples/WEBSERVICES.zip
4
The Header
The Webservices application posts the XML through an SSL secure socket connection and
authenticates the request via the received header. The header utilises Basic authentication and
must include the following information:
Type: text/xml;charset=utf-8
Content-Length:<LENGTHOFPOST>
Accept: text/xml
Accept-Encoding: gzip
Authorization:<BASICAUTHCREDENTIALSHERE>
User-Agent:<YOURSOFTWAREVERSIONHERE>
Host: webservices.securetrading.net
Connection: close
A breakdown of all the sections of the header can be found in the Web Services User Guide:
http://www.securetrading.com/files/documentation/STPP-Web-Services-User-Guide.pdf
One of the most important parts of the header is the “Authorization”, which consists of a base64
encoded string containing the username and password for your Webservices system (separated
by a colon).
For example:
Username: [email protected]
Password: pa55word
Separated by a colon: [email protected]:pa55word
Encoding the above gives us:
Base64 encode: d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=
Therefore, for the example above, the HTTPS header should include:
Authorization: Basic d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=
© Secure Trading Limited 2014
9 October 2014
Page 6 / 9
ST2K to STPP XML Migration Guide
A full example XML Request, including the header information, would look like this:
POST /xml/ HTTP/1.0
Content-Type: text/xml;charset=utf-8
Content-Length: 839
Accept: text/xml
Accept-Encoding: gzip
Authorization: <BASICAUTHCREDENTIALSHERE>
User-Agent: <YOURSOFTWAREVERSIONHERE>
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>
A Java example of how to build the request is provided here:
http://webapp.securetrading.net/examples/WEBSERVICES/Post.java
A PHP example of how to build the request is provided here:
http://webapp.securetrading.net/examples/WEBSERVICES/Post.php
© Secure Trading Limited 2014
9 October 2014
Page 7 / 9
ST2K to STPP XML Migration Guide
5
Response
In addition to the request, your system will also need to 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 found here:
http://www.securetrading.com/files/documentation/STPP-XML-Specification.pdf
© Secure Trading Limited 2014
9 October 2014
Page 8 / 9
ST2K to STPP XML Migration Guide
6
Additional notes
6.1
Testing
You will be provided with a “test” site reference and a “live” site reference. On STPP, 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.
Please refer to Testing document for further information:
http://www.securetrading.com/files/documentation/STPP-Testing.pdf
6.2
Further information on Web Services
For further information on configuring Web Services, please refer to the Web Services User
Guide:
http://www.securetrading.com/files/documentation/STPP-Web-Services-User-Guide.pdf
© Secure Trading Limited 2014
9 October 2014
Page 9 / 9