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. Mobile SDK processes 3-D Secure authentication and Authorisation
  2. Mobile SDK processes 3-D Secure authentication, then Authorisation processed through Webservices API

 

 

1. Mobile SDK processes 3-D Secure authentication and Authorisation

If you are relying on the Mobile SDK 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

typeDescriptions 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","termurl":"https:\/\/payments.securetrading.net\/process\/payments\/mobilesdklistener","requesttypedescriptions":["ACCOUNTCHECK","THREEDQUERY","AUTH"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","termurl":"https:\/\/payments.securetrading.net\/process\/payments\/mobilesdklistener","requesttypedescriptions":["RISKDEC","ACCOUNTCHECK","THREEDQUERY","AUTH"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","subscriptiontype":"RECURRING","subscriptionunit":"MONTH","subscriptionfrequency":"1","subscriptionnumber":"1","subscriptionfinalnumber":"12","subscriptionbegindate":"2020-01-01","credentialsonfile":"1","requesttypedescriptions":["RISKDEC","ACCOUNTCHECK","THREEDQUERY","AUTH","SUBSCRIPTION"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","termurl":"https:\/\/payments.securetrading.net\/process\/payments\/mobilesdklistener","requesttypedescriptions":["RISKDEC","THREEDQUERY","AUTH"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","subscriptiontype":"RECURRING","subscriptionunit":"MONTH","subscriptionfrequency":"1","subscriptionnumber":"1","subscriptionfinalnumber":"12","subscriptionbegindate":"2020-01-01","credentialsonfile":"1","requesttypedescriptions":["RISKDEC","THREEDQUERY","AUTH","SUBSCRIPTION"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","termurl":"https:\/\/payments.securetrading.net\/process\/payments\/mobilesdklistener","requesttypedescriptions":["THREEDQUERY","AUTH"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","termurl":"https:\/\/payments.securetrading.net\/process\/payments\/mobilesdklistener","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","termurl":"https:\/\/payments.securetrading.net\/process\/payments\/mobilesdklistener","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","termurl":"https:\/\/payments.securetrading.net\/process\/payments\/mobilesdklistener","requesttypedescriptions":["THREEDQUERY","ACCOUNTCHECK","SUBSCRIPTION"]},"iat":"1567701632","iss":"jwt.user"}

 

Handling the JWT response

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

External
Every JWT returned from the SDK should be verified before continuing. We provide a parsing utility that makes it easier to convert the JWT to a transaction response object. Click here for an example on how to use this.

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

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

 

Payload examples

{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","termurl":"https:\/\/payments.securetrading.net\/process\/payments\/mobilesdklistener","requesttypedescriptions":["ACCOUNTCHECK","THREEDQUERY"]},"iat":1559033849,"iss":"jwt.user"}
{"payload":{"accounttypedescription":"ECOM","baseamount":"1050","currencyiso3a":"GBP","sitereference":"test_site12345","termurl":"https:\/\/payments.securetrading.net\/process\/payments\/mobilesdklistener","requesttypedescriptions":["THREEDQUERY"]},"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 multiple responses, each corresponding to a request included in the requesttypedescriptions list.

External
Every JWT returned from the SDK should be verified before continuing. We provide a parsing utility that makes it easier to convert the JWT to a transaction response object. Click here for an example on how to use this.

We recommend checking that 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
pares
XPath: /operation/pares		 Alphanumeric (65536) The pares field is returned when 3-D Secure version 1 authentication occurs and must be submitted in the AUTH request if returned to your server.

Trust Payments analyses the pares submitted in the request to determine whether or not the cardholder was successfully authenticated on their card issuer’s ACS.
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 3-D Secure version 2 authentication 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

The following AUTH request example assumes the customer’s card issuer supports 3-D Secure v2:

#!/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"}