Alternative Payment Methods (API)
Configuring your own library

If you are unsure, please contact our Support Team for assistance.

Please ensure that any additional debugging enabled whilst testing your integration is disabled prior to going live. Failing to do so may contravene the requirements needed to maintain PCI compliance.

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

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

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.

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.

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.

Process requests using our Webservices API
Your server will now need to generate a request using your own library. For example:
"sitereference": "test_site12345", "requesttypedescriptions": ["AUTH"], "accounttypedescription": "ECOM", "currencyiso3a": "GBP", "baseamount": "1050", "orderreference": "My_Order_123", "pan": "4111111111111111", "expirydate": "12/2022", "securitycode": "123"
<request type="AUTH"> <merchant> <orderreference>My_Order_123</orderreference> </merchant> <billing> <payment> <expirydate>12/2022</expirydate> <pan>4111111111111111</pan> <securitycode>123</securitycode> </payment> <amount currencycode="GBP">1050</amount> </billing> <operation> <sitereference>test_site12345</sitereference> <accounttypedescription>ECOM</accounttypedescription> </operation> </request>



You must use a valid domain that is accessible by Trust Payments.
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.
In addition, you will need to send the request string and headers as shown in the example below:
{"alias":"[email protected]","version":"1.00","request":[{"currencyiso3a":"GBP","requesttypedescriptions":["AUTH"],"sitereference":"test_site12345","baseamount":"1050","orderreference":"My_Order_123","accounttypedescription":"ECOM","pan":"4111111111111111","expirydate":"12\/2022","securitycode":"123"}]}
{ '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' }
<requestblock version="3.67"> <alias>[email protected]</alias> <request type="AUTH"> <merchant> <orderreference>My_Order_123</orderreference> </merchant> <billing> <payment> <expirydate>12/2020</expirydate> <pan>4111111111111111</pan> <securitycode>123</securitycode> </payment> <amount currencycode="GBP">1050</amount> </billing> <operation> <sitereference>test_site12345</sitereference> <accounttypedescription>ECOM</accounttypedescription> </operation> </request> </requestblock>
Content-length: <LENGTH OF POST> Content-type: text/xml;charset=utf-8 Authorization: <BASIC AUTH CREDENTIALS HERE> Accept: text/xml
How to construct header All requests submitted to Trust Payments through our Webservices API must begin with a series of headers as defined below. We use these to identify and manage incoming requests. 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 will always be set as: charset must be the charset of the post, for example “utf-8”. 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. “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 [email protected] and password pa55word. Base64 encode [email protected]:pa55word to get d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ= Final value to include in the header in this case would be: Basic d2Vic2VydmljZXNAZXhhbXBsZS5jb206cGE1NXdvcmQ= 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 Your system will be returned numerous fields in the response object. You will need to interpret the contents of these fields to ensure they are the values expected. The following is an example of an AUTH response: It is especially important to check the Error Code and settle status values returned in the response. In addition to processing authorisations, Trust Payments supports numerous other request types. For further information on these request types, please refer to the other pages within our online documents. Summary At this point, you should be able to process a basic request using our Webservices API. Next steps If you have any questions about configuring your server, please get in touch. Use the credentials provided on this page to test your solution. When you sign up, you will be provided with a “live” account and a “test” account (the latter is prefixed with “test_”). Before you begin testing… Please be aware of the following notes: The table below lists test card numbers and customer information that can be submitted to our test bank, along with the responses that should be expected in return. The following payment credentials can be used for testing 3-D Secure v2 (a form of SCA): The following payment credentials can be used for testing 3-D Secure v1 (a form of SCA): To test for different 3-D Secure status values, follow the instructions displayed in the authentication prompt shown on the page (an example is shown below). In the textbox provided, you can enter different PIN values to test for different cases. For Payment Pages: With 3-D Secure enabled on your site reference, process a payment using one of the card numbers listed above and your browser will display an authentication prompt with instructions. For JavaScript Library implementations: After your payment form has been updated to reference our JavaScript library, process a payment using one of the card numbers listed above and your browser will display an authentication prompt with instructions. For Mobile SDK implementations: After your Android or iOS app has been updated to utilise our Mobile SDK, process a payment using one of the card numbers listed above and your app will display an authentication prompt with instructions. The authentication prompt will only be displayed for non-frictionless test card details. Frictionless cards will bypass authentication. In this case, the payment will be processed immediately (without being prompted by the browser for information). Follow the instructions displayed within the authentication prompt to complete the payment: If you haven’t already, please read our AVS and Security code documentation before testing: The following tables list test details that can be submitted to obtain different responses from the AVS and Security Code Checks. These details can be used with most major payment types. When processing recurring payments, some acquirers may return an acquirer advice code in the response. The acquirer advice code is a numeric value used to indicate if further recurring payments can be processed for the given card. You can test that your system responds appropriately to different acquirer advice codes by processing transactions with the following attributes: Please refer to the following resources when testing Protect Plus: Please refer to the following resources when testing DCC:
Content length
Content type
Authorization
Accept
Handling the response
{"requestreference":"W23-fjgvn3d8","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 15:08:47","livestatus":"0","issuer":"Test Issuer","splitfinalnumber":"1","dccenabled":"0","settleduedate":"2016-12-07","errorcode":"0","baseamount":"1050","tid":"27882788","merchantnumber":"00000000","merchantcountryiso2a":"GB","transactionreference":"23-9-80006","merchantname":"Test Merchant","paymenttypedescription":"VISA","orderreference":"My_Order_123","accounttypedescription":"ECOM","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST96","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"0","maskedpan":"411111######1111","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"zO9"}
<responseblock version="3.67">
<requestreference>X6mh36u8g</requestreference>
<response type="AUTH">
<merchant>
<merchantname>example UNICODE merchantname</merchantname>
<orderreference>AUTH_VISA</orderreference>
<tid>27882788</tid>
<merchantnumber>00000000</merchantnumber>
<merchantcountryiso2a>GB</merchantcountryiso2a>
<operatorname>[email protected]</operatorname>
</merchant>
<transactionreference>23-9-80006</transactionreference>
<security>
<postcode>2</postcode>
<securitycode>2</securitycode>
<address>2</address>
</security>
<billing>
<amount currencycode="GBP">1050</amount>
<payment type="VISA">
<issuer>Test Issuer</issuer>
<issuercountry>ZZ</issuercountry>
<pan>411111######1111</pan>
</payment>
<dcc enabled="0"/>
</billing>
<authcode>TEST96</authcode>
<timestamp>2012-10-08 12:46:02</timestamp>
<settlement>
<settleduedate>2012-10-08</settleduedate>
<settlestatus>0</settlestatus>
</settlement>
<live>0</live>
<error>
<message>Ok</message>
<code>0</code>
</error>
<acquirerresponsecode>00</acquirerresponsecode>
<operation>
<splitfinalnumber>1</splitfinalnumber>
<authmethod>PRE</authmethod>
<accounttypedescription>ECOM</accounttypedescription>
</operation>
</response>
<secrand>hYWFMkiiAZ0wKHFZ</secrand>
</responseblock>
Testing
When testing, ensure requests submitted to Trust Payments reference your test sitereference.
Test card details
3-D Secure v2
(3DSv2) Test Case 1: Successful Frictionless 3-D Secure Authentication & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000001007
THREEDQUERY
Enrolled: Y
Status: Y
AUTH
Error code: 0 – Ok
DINERS / DISCOVER
6011000000001002
JCB
3337000000000008
MASTERCARD
5200000000001005
VISA (3-D Secure v2.1.0)
4000000000001000
VISA (3-D Secure v2.2.0)
4000000000002701
(3DSv2) Test Case 2: Failed Frictionless 3-D Secure Authentication & Failed Authorisation
Card type
PAN
Handling the response
AMEX
340000000001015
THREEDQUERY
Enrolled: Y
Status: N
AUTH
Error code: 60022 – Unauthenticated
DINERS / DISCOVER
6011000000001010
JCB
3337000000000990
MASTERCARD
5200000000001013
VISA (3-D Secure v2.1.0)
4000000000001018
VISA (3-D Secure v2.2.0)
4000000000002925
(3DSv2) Test Case 3: Attempts Stand-In Frictionless 3-D Secure Authentication & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000001023
THREEDQUERY
Enrolled: Y
Status: A
AUTH
Error code: 0 -Ok
DINERS / DISCOVER
6011000000001028
JCB
3337000000007045
MASTERCARD
5200000000001021
VISA (3-D Secure v2.1.0)
4000000000001026
VISA (3-D Secure v2.2.0)
4000000000002719
(3DSv2) Test Case 4: Unavailable Frictionless 3-D Secure Authentication from the Issuer & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000001031
THREEDQUERY
Enrolled: Y
Status: U
AUTH
Error code: 0 – Ok
DINERS / DISCOVER
6011000000001036
JCB
3337000000000735
MASTERCARD
5200000000001039
VISA (3-D Secure v2.1.0)
4000000000001034
VISA (3-D Secure v2.2.0)
4000000000002313
(3DSv2) Test Case 5: Rejected Frictionless 3-D Secure Authentication by the Issuer & Failed Authorisation
Card type
PAN
Handling the response
AMEX
340000000001049
THREEDQUERY
Enrolled: Y
Status: R
AUTH
Error code: 60022 – Unauthenticated
DINERS / DISCOVER
6011000000001044
JCB
3337000000000321
MASTERCARD
5200000000001047
VISA (3-D Secure v2.1.0)
4000000000001042
VISA (3-D Secure v2.2.0)
4000000000002537
(3DSv2) Test Case 6: 3-D Secure Authentication Not Available on Lookup & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000001056
THREEDQUERY
Enrolled: U
Status: None
AUTH
Error code: 0 – Ok
DINERS / DISCOVER
6011000000001051
JCB
3337000000006765
MASTERCARD
5200000000001054
VISA (3-D Secure v2.1.0)
4000000000001059
VISA (3-D Secure v2.2.0)
4000000000002990
(3DSv2) Test Case 7: Error on Lookup & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000001064
THREEDQUERY
Enrolled: U
Status: None
AUTH
Error code: 0 – Ok
DINERS / DISCOVER
6011000000001069
JCB
3337000000000016
MASTERCARD
5200000000001062
VISA (3-D Secure v2.1.0)
4000000000001067
VISA (3-D Secure v2.2.0)
4000000000002446
(3DSv2) Test Case 8: Timeout on cmpi_lookup Transaction & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000001072
THREEDQUERY
Enrolled: U
Status: None
AUTH
Error code: 0 – Ok
DINERS / DISCOVER
6011000000001077
JCB
3337000000000081
MASTERCARD
5200000000001070
VISA (3-D Secure v2.1.0)
4000000000001075
VISA (3-D Secure v2.2.0)
4000000000002354
(3DSv2) Test Case 9: Successful Step Up 3-D Secure Authentication & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000001098
THREEDQUERY
Enrolled: Y
Status: C
AUTH
Error code: 0 – Ok
DINERS / DISCOVER
6011000000001093
JCB
3337000000200004
MASTERCARD
5200000000001096
VISA (3-D Secure v2.1.0)
4000000000001091
VISA (3-D Secure v2.2.0)
4000000000002503
(3DSv2) Test Case 10: Failed Step Up 3-D Secure Authentication & No Authorisation
Card type
PAN
Handling the response
AMEX
340000000001106
THREEDQUERY
Enrolled: Y
Status: C
AUTH
Not performed
DINERS / DISCOVER
6011000000001101
JCB
3337000000200087
MASTERCARD
5200000000001104
VISA (3-D Secure v2.1.0)
4000000000001109
VISA (3-D Secure v2.2.0)
4000000000002370
(3DSv2) Test Case 11: Step Up 3-D Secure Authentication is Unavailable & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000001114
THREEDQUERY
Enrolled: Y
Status: C
AUTH
Error code: 0 – Ok
DINERS / DISCOVER
6011000000001119
JCB
3337000000200079
MASTERCARD
5200000000001112
VISA (3-D Secure v2.1.0)
4000000000001117
VISA (3-D Secure v2.2.0)
4000000000002420
(3DSv2) Test Case 12: Error on 3-D Secure Authentication & No Authorisation
Card type
PAN
Handling the response
AMEX
340000000001122
THREEDQUERY
Enrolled: Y
Status: C
AUTH
Not performed
DINERS / DISCOVER
6011000000001127
JCB
3337000000200046
MASTERCARD
5200000000001120
VISA (3-D Secure v2.1.0)
4000000000001125
VISA (3-D Secure v2.2.0)
4000000000002644
(3DSv2) Test Case 13: Bypassed 3-D Secure Authentication & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000001080
THREEDQUERY
Enrolled: B
Status: None
AUTH
Error code: 0 – Ok
DINERS / DISCOVER
6011000000001085
JCB
3337000000000537
MASTERCARD
5200000000001088
VISA (3-D Secure v2.1.0)
4000000000001083
VISA (3-D Secure v2.2.0)
4000000000002560
3-D Secure v1
(3DSv1) Test Case 1: Successful 3-D Secure Authentication & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000003961
THREEDQUERY
Enrolled: Y
Status: None
AUTH
Error code: 0 – Ok
DINERS
3005000000006246
DISCOVER
6011000000000004
JCB
3520000000000922
MASTERCARD
5200000000000007
VISA
4000000000000002
(3DSv1) Test Case 2: Failed Signature & No Authorisation
Card type
PAN
Handling the response
AMEX
340000000006022
THREEDQUERY
Enrolled: Y
Status: None
AUTH
Not performed
DINERS
3005000000004373
DISCOVER
6011000000000012
JCB
3520000000002811
MASTERCARD
5200000000000015
VISA
4000000000000010
(3DSv1) Test Case 3: Failed Authentication & No Authorisation
Card type
PAN
Handling the response
AMEX
340000000000033
THREEDQUERY
Enrolled: Y
Status: None
AUTH
Not performed
DINERS
3005000000005925
DISCOVER
6011000000000020
JCB
3520000000009931
MASTERCARD
5200000000000023
VISA
4000000000000028
(3DSv1) Test Case 4: Attempts/Non-Participating & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000003391
THREEDQUERY
Enrolled: Y
Status: A
AUTH
Error code: 0 – Ok
DINERS
3005000000005271
DISCOVER
6011000000000038
JCB
3520000000004767
MASTERCARD
5200000000000908
VISA
4000000000000101
(3DSv1) Test Case 6: Not Enrolled & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000008135
THREEDQUERY
Enrolled: N
Status: None
AUTH
Error code: 0 – Ok
DINERS
3005000000007269
DISCOVER
6011000000000053
JCB
3520000000006903
MASTERCARD
5200000000000056
VISA
4000000000000051
(3DSv1) Test Case 7: Unavailable & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000007780
THREEDQUERY
Enrolled: U
Status: None
AUTH
Error code: 0 – Ok
DINERS
3005000000006030
DISCOVER
6011000000000061
JCB
3520000000002423
MASTERCARD
5200000000000064
VISA
4000000000000069
(3DSv1) Test Case 8: Merchant Not Active & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000008416
THREEDQUERY
Enrolled: U
Status: None
AUTH
Error code: 0 – Ok
DINERS
3005000000004837
DISCOVER
6011000000000079
JCB
3520000000006549
MASTERCARD
5200000000000072
VISA
4000000000000077
(3DSv1) Test Case 9: cmpi_lookup error & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000006337
THREEDQUERY
Enrolled: U
Status: None
AUTH
Error code: 0 – Ok
DINERS
3005000000009877
DISCOVER
6011000000000087
JCB
3520000000002175
MASTERCARD
5200000000000080
VISA
4000000000000085
(3DSv1) Test Case 10: cmpi_authenticate error & No Authorisation
Card type
PAN
Handling the response
AMEX
340000000009299
THREEDQUERY
Enrolled: Y
Status: None
AUTH
Not performed
DINERS
3005000000005602
DISCOVER
6011000000000095
JCB
3520000000006861
MASTERCARD
5200000000000098
VISA
4000000000000093
(3DSv1) Test Case 11: Authentication Unavailable & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340000000000116
THREEDQUERY
Enrolled: Y
Status: None
AUTH
Error code: 0 – Ok
DINERS
3005000000007376
DISCOVER
6011000000000103
JCB
3520000000005780
MASTERCARD
5200000000000031
VISA
4000000000000036
(3DSv1) Test Case 12: Bypassed Authentication & Successful Authorisation
Card type
PAN
Handling the response
AMEX
340099000000001
THREEDQUERY
Enrolled: B
Status: None
AUTH
Error code: 0 – Ok
DINERS
3000990000000006
DISCOVER
6011990000000006
JCB
3500990000000001
MASTERCARD
5200990000000009
VISA
4000990000000004
3-D Secure status testing
Testing AVS and security code checks
Link to Payment Pages docs / Link to API docsPremise
Billing premise
Security response
Security response caption
No 789
2
Matched
No 123
4
Not Matched
No 333
1
Not Checked
Leave blank
0
Not Given
Postcode / ZIP code
Billing postcode
Security response
Security response caption
UK
US
TE45 6ST
55555
2
Matched
TE12 3ST
12345
4
Not Matched
TE33 3ST
33333
1
Not Checked
Leave blank
Leave blank
0
Not Given
Security code
Security code
AMEX security code
Security response
Security response
123
1234
2
Matched
214
2144
4
Not Matched
333
3333
1
Not Checked
Leave blank
Leave blank
0
Not Given
Testing non-card payment methods
Link to Payment Pages docs / Link to Webservices API docs
Testing recurring payments
Testing for the acquirer advice code
Code
Description
Action
0
N/A
No action required
1
New account information available (Mastercard only)
Query customer for updated payment details
2
Cannot approve at this time
Try again later. If you are continuing to have difficulties, please contact your acquiring bank
4
Do not try again
Do not process further recurring transactions
8
Payment blocked by card scheme
Where to find the acquirer advice code
How to test for different acquirer advice codes
Visa
Acquirer advice code returned
Card number
Base amount
0
4111111111111111
1050
2
4000000000000671
1002
4
4000000000000671
1004
8
4000000000000671
1008
Mastercard
Acquirer advice code returned
Card number
Base amount
0
5100000000000511
1050
1
5100000000000271
1001
2
5100000000000271
1002
4
5100000000000271
1004
8
5100000000000271
1008
Testing Protect Plus
Testing DCC