Contents

Troubleshooting

 

“400 Bad Request”

The JSON standard mandates that string characters are encoded using UTF-8. Such characters may result in multiple bytes per character. Any JSON request that is not well-formed according to the JSON standard will not be processed successfully.

To address this issue:

 

“401 Authorization Required”

The following is an example response that may be returned:


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

To address this issue:

 

“10205 Malformed JSON”

The following is an example response that may be returned:


{"requestreference":"W23-rd55dned","version":"1.00","response":[{"errorcode":"10205","requesttypedescription":"ERROR","transactionstartedtimestamp":"2016-11-10 12:18:50","errormessage":"Malformed JSON","errordata":["invalid json"]}],"secrand":"Z0Xk"}

To address this issue:

 

“60018 Invalid requesttype”

The following is an example response that may be returned:


{"requestreference":"W72-g9wv2j5c","version":"1.00","response":[{"errorcode":"60018","requesttypedescription":"ERROR","transactionstartedtimestamp":"2017-04-19 12:56:11","errormessage":"Invalid requesttype"}],"secrand":"qTFlr"}

The above error can be caused when malformed JSON is submitted in the request.

To address this issue:

 

“60019 No searchable filter specified”

The following is an example response that may be returned:


{"requestreference":"W72-g9wv2j5c","version":"1.00","response":[{"errorcode":"60019","requesttypedescription":"TRANSACTIONUPDATE","transactionstartedtimestamp":"2016-11-29 12:06:42","errormessage":"No searchable filter specified"}],"secrand":"qTFlr"}

To address this issue:

First of all, ensure that you have specified a supported filter in the request, and that this has been spelt correctly. If the error still occurs, this could be because the formatting of the filter fields is incorrect. Please ensure the filter tag has the same structure as in the examples provided in the transaction query or transaction update documentation, depending on the type of request you are attempting to submit.

 

Transaction update errors

If you are having problems when performing updates, please check the following:

 

Error code Error message Next steps
0 Ok The update was processed successfully.
30000 Invalid field The errordata field returned in the response should contain the name of the field that was submitted with invalid data. Please ensure the data meets our specification.
60011 Wrong number of transactions Only one transaction can be updated in a TRANSACTIONUPDATE request. Please ensure the filters specify only one valid transaction.
60013 No valid updates specified You are only able to update the fields listed on the Transaction Updates page. If you attempt to update any other fields, you will be returned this message in the response.
60014 Transaction reference not found Please ensure you have submitted the correct transaction reference in the request.
60016 settlebaseamount too large When updating the transaction settlebaseamount, the value can never be greater than the amount originally authorised by your bank. Therefore, please ensure this value is equal to or lower than the authorised amount.
60017 Transaction not updatable Transactions can only be updated when in settlestatus “0”, “1” or “2”. Click here to learn more about settlement.
60018 Invalid requesttype You can only update requests with the request types listed on the Transaction Updates page.
60019 No searchable filter specified Please ensure you have submitted valid filters in the request, so we can correctly identify the transaction you would like to update.

 

Life ring

We’re here to help

If you require further assistance, please get in touch with our Support Team.

Configuring your own library

 

Warning
The following content assumes you have obtained the necessary PCI certification to process and submit sensitive cardholder data in the request to our Webservices API.

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

Padlock
You must never log sensitive payment details on your server

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.

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

 


 

Configuration

Secure Connection

Your library will need to establish a secure connection to either:

Replace <DOMAIN> with a supported Webservices domain. Click here for a full list.

 

Warning
Any connections between your server and Trust Payments Web Services 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:

Info

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

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.

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

Info
Prior to every request submitted to Webservices, 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.

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

 

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:

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

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

Info
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.
Info
You may need to open your firewall to our Web Services IPs.

Click here for a full list.

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

 


 

Your library will need to establish a secure connection to either:

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

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

 

Info
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 [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=

 

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

 

Handling the response

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:


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

 

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.

 


 

Status good

Summary

At this point, you should be able to process a basic request using our Webservices API.

 

Next steps

  • We recommend reading our Best practices in order to learn how to best handle the fields returned in the response.
  • You can refer to our additional documents to learn about other features that can be configured as part of your implementation.
  • Once you have tested your solution thoroughly, you can request to go live and begin to process live payments!

 

Life ring
Need assistance?

If you have any questions about configuring your server, please get in touch.

 

Testing

 

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_”).
When testing, ensure requests submitted to Trust Payments reference your test sitereference.

Warning
It is important to thoroughly test your integration using your test sitereference before processing live payments.

Info

Before you begin testing…

Please be aware of the following notes:

 

  • Most fields submitted to our test system will be accepted. Any data breaching its defined specification will return an error message.
  • Any test data that generates a successful response when submitted while a merchant is in test mode, will produce a declined response when a merchant is switched into live mode. In some cases, the test data may return an error response.
  • Our test system attempts to simulate responses in a similar fashion to the live system. However, depending on your acquirer you may find some responses differ slightly from those given by the test system.
  • In the interest of security, we recommend against using real payment details when using your test account.
  • We recommend specifying the main amount “10.50” when testing. Other amounts can be used but may return unexpected responses.

 


 

Test card details

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.

Warning
Do not use these credentials when processing transactions on your live site reference.
Info
While testing, all card types are supported, but when using your live account, you will receive an error if you do not have a valid merchant number for the payment type submitted.

 

 

3-D Secure v2

The following payment credentials can be used for testing 3-D Secure v2 (a form of SCA):

 

Test case Visa Mastercard American Express
Success frictionless 4000000000001026 5200000000001005 340000000001007
Success step-up 4000000000001091 5200000000001096 340000000001098
Failed frictionless 4000000000001018 5200000000001013 340000000001015
Failed step-up 4000000000001109 5200000000001104 340000000001106
Declined 4242424242424242 5100000000000412 300000000000512

 

3-D Secure v1

The following payment credentials can be used for testing 3-D Secure v1 (a form of SCA):

 

Visa-branded cards

Visa
Credit Debit V Pay Electron Purchasing
Enrolled (Y) 4111110000000211 4006260000002473 4370000000000111 4245190000000311 4484000000000411
Not enrolled (N) 4111110000000021 4006260000002481 4370000000000921 4245190000000121 4484000000000221
Unknown enrollment (U) 4111110000000401 4006260000002408 4370000000002307 4245190000000501 4484000000000601

 

Mastercard-branded cards

Test case Mastercard
Credit Debit Maestro (Intl.) Maestro (UK)
Enrolled (Y) 5100000000000511

2221000000000611

5124990000000911 5000000000000611 6759000000000711
Not enrolled (N) 5100000000000321

2221000000000991

5124990000000721 5000000000000421 6759000000000521
Unknown enrollment (U) 5100000000000701

2221000000000801

5124990000000101 5000000000000801 6759000000000901

 

3-D Secure status testing

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.

URL
Displaying the test ACS page

 

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.

 

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:

 

 

 

Non 3-D Secure

The following card types are not currently processed using 3-D Secure (a form of SCA):

 

Card type Authorisation Decline Expiry date Security code
DINERS 3000000000000111 3000000000000012 12/2030 123
DISCOVER 6011000000000301 6011000000000202 12/2030 123
JCB 3528000000000411 3528000000000312 12/2030 123

 

After the payment has been processed, the error code and status values stored with the processed AUTH are used to convey the final outcome.

Info
When the status is “N”, indicating the customer failed authentication, the errorcode “60022” will be returned.

 


 

Testing AVS and security code checks

If you haven’t already, please read our AVS and Security code documentation before testing:
Link to Payment Pages docs / Link to API docs

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.

Info
Only the billing premise, billing postcode and security code field values dictate the outcome of the AVS and security code checks performed. As such, entering any details into the other address fields will not affect the outcome of these checks.

 

Premise

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

URL
The procedure to follow when testing non-card payment methods will vary. For the most relevant testing information, please refer to the documentation provided for the specific payment method:
Link to Payment Pages docs / Link to API docs

 


 

Testing recurring payments

Testing for the acquirer advice code

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.

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

You can test that your system responds appropriately to different acquirer advice codes by processing transactions with the following attributes:

Visa
Acquirer advice code returned Card number Base amount
0 4111111111111111 1050
2 4000000000000671 1002
4 4000000000000671 1004
8 4000000000000671 1008

 

PAYMENT MASTERCARD
Acquirer advice code ‘1’ can only be returned for recurring Mastercard transactions.
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

If you haven’t already, please read our Protect Plus document before testing:
Link to Payment Pages docs / Link to API docs

Use the following baseamount values in RISKDEC requests to simulate the different possible responses from the Protect Plus checks:

baseamount Possible fraudcontrolresponsecode returned fraudcontrolshieldstatuscode returned
1011, 2011, 3011 0100, 0150 “ACCEPT”
1033, 2033, 3033 0300, 0330, 0500 “CHALLENGE”
1044, 2044, 3044 0250, 0400, 0600, 0700, 0800, 1300 “DENY”

 

Info
The fraudcontrolshieldstatuscode and fraudcontrolresponsecode values returned in RISKDEC responses may vary when not using the baseamount values listed in the table, above.

 


 

Testing DCC

If you haven’t already, please read our DCC document before testing:
Link to Payment Pages docs / Link to API docs

The card numbers listed in this test section are associated with specific local currencies. During your integration, you can use the following international test card details in order to test your system for successful and declined DCC transactions.

Successful authorisations

Country code Currency code Visa Credit Mastercard Credit
DE EUR 4500000000000007 5500000000000004
GB GBP 4300000000002211 5311110000001511
JP JPY 4900400000000005 5590410000000006
US USD 4900460000000009 5590470000000018

Declined authorisations

Country code Currency code Visa Credit Mastercard Credit
DE EUR 4500000000002482 5500000000002422
GB GBP 4300000000002492 5311110000002402
JP JPY 4900400000002472 5590410000002432
US USD 4900460000002492 5590470000002402

 

Info
You can also use an amount of 70000 in the final currency to generate a decline response.

 

investors in people logo   pci - security standards council logo

TRUST Payments LTD, No.1 Royal Exchange, London, EC3V 3DG.
A company registered in England and Wales with Company Number 04591066. VAT Number 756265116