Contents

Additional notes

 

Updating DCC authorisations

It is possible to perform updates on DCC payments prior to settlement, by submitting a TRANSACTIONUPDATE request.

It is not possible to change the currency of the payment after it has been authorised by the acquiring bank.

Warning
It is imperative that all transactions, which use the currency conversions provided by the conversion rate provider, are settled before the dccexpirytimestamp (returned in the CURRENCYRATE response). Failing to do so (e.g. by updating the settlement date) may result in the customer paying the wrong amount and may invalidate your agreement with the conversion rate provider or acquirer.

 

Partial settlement

You can use a TRANSACTIONUPDATE request to update the settle amount of an authorised DCC payment. This can be used to settle a transaction for a lower value than was initially authorised. The remaining funds will be released by the card issuer once the authorisation code has expired (usually approx. 7 days).

The new settle amount is specified in the settlebaseamount field (this represents the amount in the customer’s currency). It must be lower than the total amount authorised in the customer’s currency.

If a partial settlement request has been processed and the customer has made the payment in the customer’s currency, the original conversion rate of the transaction is used to calculate the respective settle amount in the merchant’s currency.


#!/usr/bin/python
import securetrading
   
stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)
   
update = {
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
   },
   "updates":{"settlebaseamount":"960"}
}
   
strequest = securetrading.Request()
strequest.update(update)
stresponse = st.process(strequest) #stresponse contains the transaction response
<?php
 
if (!($autoload = realpath(__DIR__ . '/../../../autoload.php')) && !($autoload = realpath(__DIR__ . '/../vendor/autoload.php'))) {
  throw new Exception('Composer autoloader file could not be found.');
}
require_once($autoload);
 
$configData = array(
  'username' => '[email protected]',
  'password' => 'Password1^',
);
 
$requestData = array(
'requesttypedescriptions' => array('TRANSACTIONUPDATE'),
'filter' => array(
  'sitereference' => array(array('value' => 'test_site12345')),
  'transactionreference' => array(array('value' => '1-2-3'))
),
'updates' => array('settlebaseamount' => '960')
);
 
$api = \Securetrading\api($configData);
$response = $api->process($requestData);
var_dump($response->toArray());
 
?>
curl --user [email protected]:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias": "[email protected]",
"version": "1.00",
"request": [{
  "requesttypedescriptions": ["TRANSACTIONUPDATE"],
  "filter":{
    "sitereference": [{"value":"test_site12345"}],
    "transactionreference": [{"value":"1-2-3"}]
},
"updates":{"settlebaseamount":"960"}
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["TRANSACTIONUPDATE"],"filter":{"sitereference":[{"value":"test_site12345"}],"transactionreference":[{"value":"1-2-3"}]},"updates":{"settlebaseamount":"960"}}]}
<?xml version='1.0' encoding='utf-8'?>
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="TRANSACTIONUPDATE">
    <filter>
      <transactionreference>1-2-3</transactionreference>
      <sitereference>test_site12345</sitereference>
    </filter>
    <updates>
      <settlement>
        <settlebaseamount>960</settlebaseamount>
      </settlement>
    </updates>
  </request>
</requestblock>

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

 

Using your own DCC provider

If preferred, you can perform your own currency conversion without performing a CURRENCYRATE request or refer to a pre-existing parent CURRENCYRATE request. To do this, submit an AUTH request (as outlined on this page), while ensuring all the required fields are submitted using valid conversion rate details from your DCC provider.

Warning
It is your responsibility to calculate the amounts based on the conversion rates from your DCC provider, and to ensure the amounts and currencies you submit in the AUTH request are valid.
URL
Receipt text

Select acquirers may require certain information to be displayed to the customer in a receipt, following a transaction, such as the conversion rate used and the name of the conversion rate provider. Please be sure to check with your acquiring bank that you are displaying all the information required.

 

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.

 

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