Trust Payments docs Search
Contents

Payment flows and additional request types

 

The Trust Payments gateway uses request types to determine the actions that are to be performed during the payment session. These are defined in the JWT payload of the request JWT. This enables two main methods with which you can perform deeper customisation to your payment flow:

  1. JavaScript Library processes 3-D Secure authentication and Authorisation
  2. JavaScript Library processes 3-D Secure authentication, then Authorisation processed through Webservices API

 

 

1. JavaScript Library processes 3-D Secure authentication and Authorisation

If you are relying on the JavaScript Library to process a payment, additional request types can be applied to your configuration by making changes to the requesttypedescriptions list submitted within the JWT payload. When specifying alternative requests, you must ensure any additional fields required by the request types specified are also submitted in the JWT payload. Information on all considerations that need to be made when including additional request types can be found in the respective documentation, links to which can be found below:

 

Supported request types

requesttypedescriptions Summary of actions performed
[“ACCOUNTCHECK”,”THREEDQUERY”,”AUTH”]
  • The Account check is processed. This performs preliminary checks on customer’s address and security code. (Customer is not yet charged)
  • The 3-D query is then processed. This authenticates the customer using 3-D Secure.
  • The Authorisation is then processed. This processes a payment against the customer’s card.

Click here to learn more about this request.
[“RISKDEC”,”ACCOUNTCHECK”,”THREEDQUERY”,”AUTH”]
  • The Risk decision is processed. This performs a series of checks on the details submitted by the customer to check for indications fraud may have occurred.
  • The Account check is processed. This performs preliminary checks on customer’s address and security code. (Customer is not yet charged)
  • The 3-D query is then processed. This authenticates the customer using 3-D Secure.
  • The Authorisation is then processed. This processes a payment against the customer’s card.
[“RISKDEC”,”ACCOUNTCHECK”,”THREEDQUERY”,”AUTH”,”SUBSCRIPTION”]
  • The Risk decision is processed. This performs a series of checks on the details submitted by the customer to check for indications fraud may have occurred.
  • The Account check is processed. This performs preliminary checks on customer’s address and security code. (Customer is not yet charged)
  • The 3-D query is then processed. This authenticates the customer using 3-D Secure.
  • The Authorisation is then processed. This processes a payment against the customer’s card.
  • The Subscription is then processed. This schedules automated recurring payments to be debited from the customer’s card.
[“RISKDEC”,”THREEDQUERY”,”AUTH”]
  • The Risk decision is processed. This performs a series of checks on the details submitted by the customer to check for indications fraud may have occurred.
  • The 3-D query is then processed. This authenticates the customer using 3-D Secure.
  • The Authorisation is then processed. This processes a payment against the customer’s card.

Click here to learn more about this request.
[“RISKDEC”,”THREEDQUERY”,”AUTH”,”SUBSCRIPTION”]
  • The Risk decision is processed. This performs a series of checks on the details submitted by the customer to check for indications fraud may have occurred.
  • The 3-D query is then processed. This authenticates the customer using 3-D Secure.
  • The Authorisation is then processed. This processes a payment against the customer’s card.
  • The Subscription is then processed. This schedules automated recurring payments to be debited from the customer’s card.
[“THREEDQUERY”,”AUTH”]
  • The 3-D query is processed. This authenticates the customer using 3-D Secure.
  • The Authorisation is then processed. This processes a payment against the customer’s card.
[“THREEDQUERY”,”AUTH”,”RISKDEC”]
  • The 3-D query is processed. This authenticates the customer using 3-D Secure.
  • The Authorisation is then processed. This processes a payment against the customer’s card.
  • The Risk decision is then processed. This performs a series of checks on the details submitted by the customer to check for indications fraud may have occurred.

Click here to learn more about this request.
[“THREEDQUERY”,”AUTH”,”SUBSCRIPTION]
  • The 3-D query is processed. This authenticates the customer using 3-D Secure.
  • The Authorisation is then processed. This processes a payment against the customer’s card.
  • The Subscription is then processed. This schedules automated recurring payments to be debited from the customer’s card.

Click here to learn more about this request.
[“THREEDQUERY”,”ACCOUNTCHECK”,”SUBSCRIPTION]
  • The 3-D query is processed. This authenticates the customer using 3-D Secure.
  • The Account check is then processed. This performs preliminary checks on customer’s address and security code and performs tokenization. The customer is not charged, but their payment credentials are stored by Trust Payments for future transactions.
  • The Subscription is then processed. This schedules automated recurring payments to be debited from the customer’s card.

Click here to learn more about this request.

 

Payload examples

{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","requesttypedescriptions":["ACCOUNTCHECK","THREEDQUERY","AUTH"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","requesttypedescriptions":["RISKDEC","ACCOUNTCHECK","THREEDQUERY","AUTH"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","requesttypedescriptions":["RISKDEC","ACCOUNTCHECK","THREEDQUERY","AUTH","SUBSCRIPTION"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","requesttypedescriptions":["RISKDEC","THREEDQUERY","AUTH"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","requesttypedescriptions":["RISKDEC","THREEDQUERY","AUTH","SUBSCRIPTION"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","requesttypedescriptions":["THREEDQUERY","AUTH"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","requesttypedescriptions":["THREEDQUERY","AUTH","RISKDEC"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencycode":"GBP","sitereference":"test_site12345","subscriptiontype":"RECURRING","subscriptionunit":"MONTH","subscriptionfrequency":"1","subscriptionnumber":"1","subscriptionfinalnumber":"12","subscriptionbegindate":"2020-01-01","credentialsonfile":"1","requesttypedescriptions":["THREEDQUERY","AUTH","SUBSCRIPTION]},"iat":"1567701632","iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencycode":"GBP","sitereference":"test_site12345","subscriptiontype":"RECURRING","subscriptionunit":"MONTH","subscriptionfrequency":"1","subscriptionnumber":"1","subscriptionfinalnumber":"12","subscriptionbegindate":"2020-01-01","credentialsonfile":"1","requesttypedescriptions":["THREEDQUERY","ACCOUNTCHECK","SUBSCRIPTION]},"iat":"1567701632","iss":"jwt.user"}

 

Handling the JWT response

The contents of the response is dependent on whether the customer was subject to more stringent authentication (referred to as “Step-up” authentication).

 

If “Step-up” authentication

After the customer has completed the payment session, you will receive a single response JWT, consisting of responses of all requests that occurred after the threeDQuery request. The most important response to check is that of the Auth, which is where the transaction is authorised by the issuing bank. If the Auth has failed, the payment will be unsuccessful. Ensure that the errorcode value returned is “0”, indicating success.

 

If “Frictionless”

After the customer has completed the payment session, you will receive a single response JWT consisting of multiple responses, each corresponding to a request included in the requestTypes list. The most important response to check is that of the Auth, which is where the transaction is authorised by the issuing bank. If the Auth has failed, the payment will be unsuccessful. Ensure that the errorcode value returned is “0”, indicating success.

 

 

2. JavaScript Library processes 3-D Secure authentication, then Authorisation processed through Webservices API

This section allows for the following process to be performed:
(The below does not require the customer to be present for the processing of the AUTH)

  1. Process 3-D Secure authentication using our JavaScript Library.
  2. Complete payment by processing an AUTH request through our Webservices API, which can be configured on your server.
Padlock
To remain compliant with PSD2, payment requests must be performed with 3-D Secure. Because of this, it is mandatory that the Authorisation request your server submits to Trust Payments includes the fields required to verify the outcome of the 3-D Secure authentication (these are described later in this section).

 

Supported request types

requesttypedescriptions Summary of actions performed
[“ACCOUNTCHECK”,”THREEDQUERY”]
  • The Account check is processed. This performs preliminary checks on customer’s address and security code. (Customer is not yet charged)
  • The 3-D query is then processed. This authenticates the customer using 3-D Secure.
  • After this, you can perform your own back office processes as necessary, then it is your responsibility to process the Authorisation following authentication, by following the steps outlined below this table.
[“THREEDQUERY”]
  • The 3-D query is processed. This authenticates the customer using 3-D Secure.
  • After this, you can perform your own back office processes as necessary, then it is your responsibility to process the Authorisation following authentication, by following the steps outlined below this table.
[“THREEDQUERY”,”ACCOUNTCHECK”]
  • The 3-D query is processed. This authenticates the customer using 3-D Secure.
  • The Account check is then processed. This performs preliminary checks on customer’s address and security code and performs tokenization. The customer is not charged, but their payment credentials are stored by Trust Payments for future transactions.
  • After this, you can perform your own back office processes as necessary, then it is your responsibility to process the Authorisation following authentication, by following the steps outlined below this table.

 

Payload examples

{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","requesttypedescriptions":["ACCOUNTCHECK","THREEDQUERY"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","requesttypedescriptions":["THREEDQUERY"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","requesttypedescriptions":["THREEDQUERY","ACCOUNTCHECK"]},"iat":1559033849,"iss":"jwt.user"}

 

Handling the JWT response

After the customer has completed the payment session, you will receive a single response JWT consisting of one or more responses from the gateway, each corresponding to a request included in the requesttypedescriptions list. In the same manner that we recommend handling all JWT responses, your system must first recalculate the signature to verify the response is from Trust Payments (following the steps described on this page). Once this process has been completed, we recommend ensuring the errorcode value returned in all responses is “0”, indicating success.

 

Submit the Authorisation request

After the 3-D Secure authentication has been completed, your server is responsible for submitting an Authorisation request to the Trust Payments payment gateway.  You must read the schema table below and ensure the required fields are submitted in the request, as shown in the following example:

 

Authorisation field specification

Field Format Description
parenttransactionreference
XPath: /operation/parenttransactionreference		 Alphanumeric (25) Value of the transactionreference returned in the last request processed as specified in the typeDescriptions.

threedresponse
XPath: /operation/threedresponsew		 JWT The threedresponse field is returned when the customer is challenged during authentication for 3-D Secure versions 1 and 2, and must be submitted in the AUTH request if returned to your server.

Trust Payments analyses the threedresponse submitted in the request to determine whether or not the cardholder was successfully authenticated on their card issuer’s ACS.

Failure to submit the threedresponse in the AUTH when present in the JWT response may lead to the liability shift being forfeited.

 

 

Code example

#!/usr/bin/python
import securetrading

stconfig = securetrading.Config()
stconfig.username = "[email protected]"
stconfig.password = "Password1^"
st = securetrading.Api(stconfig)

auth = {
  "sitereference": "test_site12345",
  "requesttypedescriptions": ["AUTH"],
  "orderreference": "My_Order_123",
  "parenttransactionreference": "1-2-345",
  "threedresponse": "XXXXX"
}

strequest = securetrading.Request()
strequest.update(auth)
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(
  'sitereference' => 'test_site12345', 
  'requesttypedescriptions' => array('AUTH'),
  'orderreference' => 'My_Order_123',
  'parenttransactionreference' => '1-2-345',
  'threedresponse' => 'XXXXX'
);

$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": ["AUTH"],
  "sitereference": "test_site12345",
  "orderreference": "My_Order_123",
  "parenttransactionreference": "1-2-345",
  "threedresponse": "XXXXX"
}]}'
{"alias":"[email protected]","version":"1.00","request":[{"requesttypedescriptions":["AUTH"],"sitereference":"test_site12345","orderreference":"My_Order_123","parenttransactionreference":"1-2-345","threedresponse":"XXXXX"}]}
<requestblock version="3.67">
  <alias>[email protected]</alias>
  <request type="AUTH">
    <merchant>
      <orderreference>My_Order_123</orderreference>
    </merchant>
    <operation>
      <sitereference>test_site12345</sitereference>
	  <parenttransactionreference>1-2-345</parenttransactionreference>
	  <threedresponse>XXXXX</threedresponse>
    </operation>
  </request>
</requestblock>

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

 

Handle the Authorisation response

Finally, your server will be returned an Authorisation response:

{"requestreference":"W23-n68rw97k","version":"1.00","response":[{"transactionstartedtimestamp":"2016-12-07 17:21:59","parenttransactionreference":"1-2-345","livestatus":"0","issuer":"SecureTrading Test Issuer1","xid":"NmVxNGtsTDBkSVJzcmwrSnEyMFc=","dccenabled":"0","settleduedate":"2016-12-08","errorcode":"0","tid":"00000000","merchantnumber":"00000000","merchantcountryiso2a":"GB","status":"Y","transactionreference":"1-2-346","merchantname":"Test Merchant","paymenttypedescription":"VISA","baseamount":"100","enrolled":"Y","eci":"05","accounttypedescription":"ECOM","cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=","acquirerresponsecode":"00","requesttypedescription":"AUTH","securityresponsesecuritycode":"2","currencyiso3a":"GBP","authcode":"TEST","errormessage":"Ok","operatorname":"[email protected]","securityresponsepostcode":"2","maskedpan":"411111######0211","securityresponseaddress":"0","issuercountryiso2a":"US","settlestatus":"0"}],"secrand":"bsZP"}