The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our 3DS API.
Read this article to learn more.
Before you get started, you will need a Web Services username and password to allow us to authenticate your requests
You can create a Web Services user using our MyST interface. Your system will need to submit this username in every request, along with the password. In our request examples we use a placeholder username and password, which you will need to replace with your own credentials before testing.
If you don’t already have Web Services credentials, click here to learn how to configure this.
You will also need to contact our Support Team and request a new 3DS API test site reference is created for you to begin testing with our 3DS API
It is important to note that you cannot use existing site reference(s), which are already configured to process payments, to process requests to our 3DS API.
This means if you are processing authentication requests to our 3DS API and payment authorisation requests to our Webservices API, this will require different site references for each use case.
Configuration
Secure Connection
Your library will need to establish a secure connection to either:
- “https://<DOMAIN>/json/” (for JSON – recommended)
- “https://<DOMAIN>/xml/” (for XML)
Replace <DOMAIN> with a supported Webservices domain. Click here for a full list.
Any connections between your server and Trust Payments must be properly authenticated and encrypted
Trust Payments 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.2 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 Trust Payments 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.
- Your library and code base must be maintained and you must regularly update to the latest security patches and/or features.
Trust Payments uses the Digicert Certificate Authority to sign all certificates. Your SSL/TLS library must be configured to trust all Digicert certificates:
https://www.digicert.com/digicert-root-certificates.htm
Note: Most up-to-date Operating Systems should already have the Digicert Roots trusted and in their trust store by default, meaning most merchants will not need to take any action to support this requirement. However, if merchants are not using the built-in OS trust store, and are instead creating their own trust store, then they should add all of the Digicert Root certificates to their custom trust store, because our certificates could be signed by any of the active Digicert root certificates in the future.
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 Trust Payments 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.
Most SSL/TLS library implementations will fulfill 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.
Load Balancing
Trust Payments 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.
Prior to every request submitted using our 3DS API, you must perform a DNS lookup to the correct domain in your application to obtain the IP of an available gateway.
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 Trust Payments and refresh your DNS entries when the TTL expires.
Trust Payments has a number of DNS servers used to serve DNS records. It is important that your server has the ability to connect to any 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 problems when trying to resolve payment system URLs.
From a debug perspective, you can execute the following command to obtain the current list of DNS servers available:
- For European Gateway:
- Windows: nslookup -type=NS securetrading.net
- Linux: dig NS securetrading.net
- For US Gateway:
- Windows: nslookup -type=NS securetrading.us
- Linux: dig NS securetrading.us
Timeouts
In the unlikely event that your system encounters problems when connecting to us, 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.
Process requests using our 3DS API
We will accept any Unicode characters in your request. The encoding used is UTF-8, which is a multi-byte encoding scheme. All responses from us are encoded using UTF-8. Your system must be prepared to accept any valid responses encoded this way.
You may need to open your firewall to our Web Services IPs.
Click here for a full list.
In order to meet strict security requirements we are unable to accept an origin of https://localhost when using our Cross-origin resource sharing (CORS) services.
You must use a valid domain that is accessible by Trust Payments.
In addition, you will need to use the headers format as shown in the example below:
{
'Content-length': '<LENGTH OF POST>',
'Content-type': 'application/json',
'Authorization': '<BASIC AUTH CREDENTIALS HERE>',
'Accept': 'text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8'
}
Content-length: <LENGTH OF POST>
Content-type: text/xml;charset=utf-8
Authorization: <BASIC AUTH CREDENTIALS HERE>
Accept: text/xmlHow to construct header
All requests submitted to Trust Payments through our 3DS API must begin with a series of headers as defined below. We use these to identify and manage incoming requests.
Content length
Content-Length must be the length of the request bytes in the chosen charset. This must be calculated after any character encoding has been performed.
Content type
Content-Type will always be set as:
- “application/json” (for JSON)
- “text/xml” (for 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 header
Our system will accept any Unicode characters. The default encoding used for JSON is UTF-8 (a multi-byte encoding scheme). Most JSON parsers will automatically handle this.
Authorization
“Basic “, followed by a base64 encoding of your Web Services credentials in the format username:password, (stripped of white-space characters).
e.g. For username webservices@example.com and password pa55word.
Base64 encode webservices@example.com:pa55word to get d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=
Final value to include in the header in this case would be: Basic d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ=
Accept
The format of the data being submitted to Trust Payments.
e.g. text/html,application/xhtml+xml,application/xml;q=0.9,image/webp,*/*;q=0.8
