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:
- Mobile SDK processes 3-D Secure authentication and Authorisation
- 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”] |
|
[“RISKDEC”,”ACCOUNTCHECK”,”THREEDQUERY”,”AUTH”] |
|
[“RISKDEC”,”ACCOUNTCHECK”,”THREEDQUERY”,”AUTH”,”SUBSCRIPTION”] |
|
[“RISKDEC”,”THREEDQUERY”,”AUTH”] |
|
[“RISKDEC”,”THREEDQUERY”,”AUTH”,”SUBSCRIPTION”] |
|
[“THREEDQUERY”,”AUTH”] |
|
[“THREEDQUERY”,”AUTH”,”RISKDEC”] |
|
[“THREEDQUERY”,”AUTH”,”SUBSCRIPTION] |
|
[“THREEDQUERY”,”ACCOUNTCHECK”,”SUBSCRIPTION] |
|
Payload examples
- ["ACCOUNTCHECK","THREEDQUERY","AUTH"]
- ["RISKDEC","ACCOUNTCHECK","THREEDQUERY","AUTH"]
- ["RISKDEC","ACCOUNTCHECK","THREEDQUERY","AUTH","SUBSCRIPTION"]
- ["RISKDEC","THREEDQUERY","AUTH"]
- ["RISKDEC","THREEDQUERY","AUTH","SUBSCRIPTION"]
- ["THREEDQUERY","AUTH"]
- ["THREEDQUERY","AUTH","RISKDEC"]
- ["THREEDQUERY","AUTH","SUBSCRIPTION"]
- ["THREEDQUERY","ACCOUNTCHECK","SUBSCRIPTION"]
{"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","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","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.

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)
- Process 3-D Secure authentication using our Mobile SDK.
- Complete payment by processing an AUTH request through our Webservices API, which can be configured on your server.

Supported request types
typeDescriptions | Summary of actions performed |
[“ACCOUNTCHECK”,”THREEDQUERY”] |
|
[“THREEDQUERY”] |
|
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.

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