STPP Web Services

insidiousbehaviorΑσφάλεια

3 Νοε 2013 (πριν από 3 χρόνια και 10 μήνες)

86 εμφανίσεις


STPP Web Services

User Guide


This document covers how to process XML Requests
and Responses using the SecureTrading Web Services
interface.


Version
1.
5

26/06/2013


STPP Web Services


© SecureTrading Limited 201
3

26/06/2013

2

of
9


About this Document


This document
covers

how to
process

XML
R
equest
s

and R
esponses
using
the SecureTrading
Web Services interface.

XML specifications can be downloaded from SecureTrading’s website
(
http://www.securetrading.com/support/downloads
-
stpp.html
).


Conventions

Terminology conventions on

“merchant” and “customer”

The supplier
-
customer chain within SecureTrading’s systems
has two levels of customer,
SecureTrading therefore make a clear definition between the two:




Merchant relates to a customer of SecureTrading that uses the system to process
requests, such as those for online payments.



Customer relates to a customer of the

merchant.

N
aming conventions of XML through SecureTrading

Whenever a field used through SecureTrading’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 SecureTrading’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 b
e included within this document:



N
otes with useful (but not m
andatory
)

info
rmation for your consideration
are
displayed

using the SecureTrading cog
,

as shown here
.



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
italics, as shown here.


System Time




SecureTrading’s System Time is in Greenwich Mean Time (GMT).

STPP Web Services


© SecureTrading Limited 201
3

26/06/2013

3

of
9


Table of Contents

1

INTRODUCTION

................................
................................
................................
..........................

4

1.1

O
VERVIEW

................................
................................
................................
................................
...

4

1.2

S
YSTEM
C
ONFIGURATION

................................
................................
................................
................

4

1.2.1

IP Ranges

................................
................................
................................
..........................

4

2

PERFORMING A REQUEST

................................
................................
................................
...........

5

2.1

S
TEP
1:

S
ECURE
T
RADING CONFIGURATION

................................
................................
.........................

5

2.2

S
TEP
2:

S
UBMIT THE REQUEST

................................
................................
................................
..........

5

2.2.1

Basic access authentication

................................
................................
..............................

5

2.2.2

Headers

................................
................................
................................
.............................

5

2.2.3

Examples

................................
................................
................................
...........................

6

2.3

I
MPORTANT
N
OTES

................................
................................
................................
........................

7

2.3.1

HTTPS

................................
................................
................................
................................

7

2.3.2

DNS

................................
................................
................................
................................
...

7

2.3.3

Handling the Certificate Authority

................................
................................
....................

8

3

FURTHER INFORMATION
AND SUPPORT

................................
................................
....................

9

3.1

S
ECURE
T
RADING
S
UPPORT

................................
................................
................................
..............

9

3.2

S
ECURE
T
RADING
S
ALES

................................
................................
................................
...................

9

3.3

U
SEFUL
D
OCUMENTS

................................
................................
................................
.....................

9

3.4

F
REQUENTLY
A
SKED
Q
UESTIONS

................................
................................
................................
.......

9


STPP Web Services


© SecureTrading Limited 201
3

26/06/2013

4

of
9


1

Introduction


The Web Servi
ces

interface
allows merchants

to submit a request
using
a

client program to
SecureTrading
,

providing
a

username and password

for
authentication
.


1.1

Overview

This document

explains and includes examples of the

SecureTrading

Web Services interface
.


1.2

System
Configuration

In order to process XML R
equests using
the Web Services interface
,
you

will need to have an
account with SecureTrading. For more information, contact SecureTrading Sales (
3.2

SecureTrading Sales

on
page
9
).

1.2.1

IP Ranges

You

may need to open
your

firewall for SecureTrading’s IP Ranges.


Current IP
R
anges can be viewed at
http://webapp.securetrading.net/ips.html




STPP Web Services


© SecureTrading Limited 201
3

26/06/2013

5

of
9


2

Performing a r
equest


To
successfully process

XML R
equests using
the SecureTrading Web Services interface
,

follow the steps outlined in this section:


2.1

Step 1:
SecureTrading
c
onfiguration

You

will need to set

up a
site reference,
username and
password

by
contact
ing

SecureTrading S
upport (
3.1

SecureTrading Support

on
page
9
).



2.2

Step 2: Submit the r
equest

After

configur
ing
your

SecureTrading account
, you can
submit
XML R
equest
s

to the Web
Services interface

by submitting a SSL POST request to:


https://webservices.securetrading.net:443/
xml/


2.2.1

Basic access authentication

Basic access authentication

is a method for a

web browser
client program to provide a

userna
me 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=


Therefore the
HTTP

header should
include
:



Authorization: Basic

d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=


2.2.2

Headers

The HTTP
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 CREDENT
I
ALS HERE>

User
-
Agent:
<YOUR SOFTWARE VERSION HERE>

Host: webservices.securetrading.net

Connection: close

Figure
1

-

HTTP Headers



Content
-
Type

will always be set as

text/xml

.




charset

must be the charset of the post, for example “
utf
-
8
”.



Content
-
Length

must be the length of the XML String.



Accept

will always be set as

text/xml

.




Accept
-
Encoding
should

always be set as


gzip

. This will compress the
response, providing your cl
ient supports this functionality.

STPP Web Services


© SecureTrading Limited 201
3

26/06/2013

6

of
9



Please n
ote

that most Web Services clients will support
gzip

encoding.

Please check with your client software provider for further information.

2.2.3

Example
s

Below

(
Figure
2
)

is an example of
how to perform
a
standard authorisation request using the
site reference

examplesite1234
”,

with the username

webservices@securetrading.com


and password

pass
word
”.



POST

/xml/ HTTP/1.0

Content
-
Type: text/xml;charset=utf
-
8

Content
-
Length: 775

Accept: text/xml

Accept
-
Encoding: gzip

Authorization:
<BASIC AUTH CREDENT
I
ALS HERE>

User
-
Agent:
<YOUR SOFTWARE VERSION HERE>

Host: webservices.securetrading.net

Connection: close


<re
questblock version="3.67">


<alias>webservices@securetrading.com</alias>


<request type="AUTH">



<operation>




<sitereference>examplesite1234</sitereference>




<accounttypedescription>ECOM</accounttypedescription>



</operation>



<merchan
t>




<orderreference>Example AUTH</orderreference>




<termurl>https://www.example.com/termurl.cgi</termurl>




<email></email>



<name>Merchant Name</name>




</merchant>




<customer>




<delivery/>




<name></name>




<email><
/email>



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

Figure
2


-

Web Services Request example


Please n
ote

a Java example can be downloaded
from

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


STPP Web Services


© SecureTrading Limited 201
3

26/06/2013

7

of
9



Please n
ote

for the XML Requests, the <
alias
> tag

will be the

same as the

Web
Services
username
.



Please n
ote

details of different XML requests can be found on our website:
http://www.securetrading.com/support/downloads
-
stpp.html
.


2.3

Important

Notes

N
otes to consider when
using

the

Web Services interface
.

2.3.1

HTTPS

All
SecureTradi
ng Web Services R
equests must be performed using

HTTPS.

2.3.2

DNS

SecureTrading employs DNS load balancing. DNS load balancing is designed to return a single
IP
,

which will be
the
preferred destination for
your
serve
r

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 e
ntire 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 SecureTrading and refresh
your

DNS entries when the TTL expires and connect to the newly returned IP.


SecureTrading 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 tryin
g to resolve payment system URL
s.



I
t is recommended to include NS lookups to securetrading.net into
your

application
to continuously obtain the current list of DNS servers
ava
ilable
.


From a debug perspective, you
can execute the following command:




Windows: nslookup
-
type=NS
securetrading
.net



Linux: dig NS securetrading.net



STPP Web Services


© SecureTrading Limited 201
3

26/06/2013

8

of
9


2.3.3

Handling the Certificate Authority

2.3.3.1

SSL / HTTPS Authentication



It is imperative that any connections

between your server and SecureTrading Web

Services

are properly authenticated and encrypted.




SecureTrading
use industry standard high
-
strength SSL/TLS encryption.

We recommend

that
you use an up
-
to
-
date SSL library implementation for your chosen lang
uage.



You should ensure it has the following capabilities:




SSLv3/TLSv1.0 or higher capabilities
.



Server authentication must be performed by validating a certificat
e chain up to a known,
trusted Certificate A
uthority (see below)
.



Server authentication m
ust 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 SecureTrading 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
.



SecureTrading use the following Certificate Authorities to sign our certificates. Your SSL

library must be configured to trust thes
e Certificate A
uthorities. Your S
SL policy should

includ
e reviewing and updating these Certificate A
uthorities
on a regular basis (e
.
g. once a
year).




V
alidating a chain to a trusted Certificate A
uthority means your implementation will not need

any changes when SecureTrading 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 provide
s


different individual c
ert
ificates. (More information on Certificate A
uthorities can be found

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

although this should not be necessary to

integrate with SecureTrading
Web

Services)


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

-

All VeriSign root certificates
should be considered trusted




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; otherwi
se 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.







STPP Web Services


© SecureTrading Limited 201
3

26/06/2013

9

of
9


3

Further Information and Support


This section provides

useful information with regards to documentation and support for
the
Merchant’s

SecureTrading solution.

3.1

SecureTrading Support

A
ny questions regarding integration or maintenance of the system, please contact our
support team using one of the following meth
ods.


Method

Details

Phone

+44 (0) 1248 672 050

Fax

+44 (0) 1248 672 099

E
-
Mail

support@securetrading.com

URL

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


3.2

SecureTrading Sales

If you do not have an account with
SecureTrading
, please contact our
S
ales team and they
will inform you of the benefits of a SecureTrading account.


Method

Details

Phone

0800 028
9151

Phone (Int’l)

+㐴
4⤠ㄲ㐸‶㜲‰70

䙡F

+㐴
4⤠ㄲ㐸‶㜲‰79

E
-
䵡楬

s慬as@se捵牥瑲WT楮朮捯g

U剌

h瑴p㨯⽷ww⹳e捵牥瑲WT楮朮捯c


3.3

Useful Documents

Any document

regarding the ST
PP

system can be found on
SecureTrading’s

website
(
http://www.securetrading.com/support/stpp/downloads.html
). Alternatively, please
contact our support team.


3.4

Frequen
tly Asked Questions

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