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
- 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.
Account Checks are subject to the following requirements:
- Account Checks are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding.
- Account Checks can only be performed for card-based payment methods.
Payload example:
{
"payload":{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"currencyiso3a":"GBP",
"sitereference":"test_site12345",
"requesttypedescriptions":["ACCOUNTCHECK","THREEDQUERY","AUTH"]
},
"iat":1559033849,
"iss":"jwt.user"
}
- 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.
Account Checks are subject to the following requirements:
- Account Checks are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding.
- Account Checks can only be performed for card-based payment methods.
Payload example:
{
"payload":{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"currencyiso3a":"GBP",
"sitereference":"test_site12345",
"requesttypedescriptions":["RISKDEC","ACCOUNTCHECK","THREEDQUERY","AUTH"]
},
"iat":1559033849,
"iss":"jwt.user"
}
- 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.
Account Checks are subject to the following requirements:
- Account Checks are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding.
- Account Checks can only be performed for card-based payment methods.
Payload example:
{
"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"
}
- 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.
Payload example:
{
"payload":{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"currencyiso3a":"GBP",
"sitereference":"test_site12345",
"requesttypedescriptions":["RISKDEC","THREEDQUERY","AUTH"]
},
"iat":1559033849,
"iss":"jwt.user"
}
- 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.
Payload example:
{
"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"
}
- 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 combination “THREEDQUERY”,”ACCOUNTCHECK” is only supported for merchants with a Trust Payments acquiring account.
Account Checks can only be performed for card-based payment methods.
Payload example:
{
"payload":{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"currencyiso3a":"GBP",
"sitereference":"test_site12345",
"requesttypedescriptions":["THREEDQUERY","ACCOUNTCHECK"]
},
"iat":1559033849,
"iss":"jwt.user"
}
- 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.
Payload example:
{
"payload":{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"currencyiso3a":"GBP",
"sitereference":"test_site12345",
"requesttypedescriptions":["THREEDQUERY","AUTH"]
},
"iat":1559033849,
"iss":"jwt.user"
}
- 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.
Payload example:
{
"payload":{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"currencyiso3a":"GBP",
"sitereference":"test_site12345",
"requesttypedescriptions":["THREEDQUERY","AUTH","RISKDEC"]
},
"iat":1559033849,
"iss":"jwt.user"
}
- 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.
Payload example:
{
"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"
}
- 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.
Account Checks are subject to the following requirements:
- Account Checks are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding.
- Account Checks can only be performed for card-based payment methods.
Payload example:
{
"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
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.
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)
- 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.
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
- 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.
Account Checks are subject to the following requirements:
- Account Checks are supported for merchants with a Trust Payments acquiring account. If you are using a different acquiring bank, you will need to contact our Support Team to check this feature is supported before proceeding.
- Account Checks can only be performed for card-based payment methods.
Payload example:
{
"payload":{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"currencyiso3a":"GBP",
"sitereference":"test_site12345",
"requesttypedescriptions":["ACCOUNTCHECK","THREEDQUERY"]
},
"iat":1559033849,
"iss":"jwt.user"
}
- 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 example:
{
"payload":{
"accounttypedescription":"ECOM",
"baseamount":"1050",
"currencyiso3a":"GBP",
"sitereference":"test_site12345",
"requesttypedescriptions":["THREEDQUERY"]
},
"iat":1559033849,
"iss":"jwt.user"
}
Forcing step-up (challenge) authentication
By submitting additional field scaexemptionindicator in the payload for request type "THREEDQUERY", you can influence whether step-up 3DS authentication is performed with the customer. The following values are supported:
- scaexemptionindicator=13 - This will request that the card issuer performs a step-up (challenge) authentication with EMV 3DS, but if the card issuer deems this unnecessary, frictionless authentication will occur and the card issuer will assume liability in most circumstances.
- scaexemptionindicator=14 - This will request that the card issuer performs a step-up (challenge) authentication with EMV 3DS in all circumstances.
In situations where a soft decline response has been returned following a payment request, you will need to process a THREEDQUERY request and include scaexemptionindicator=14 to force step-up authentication.
If cardholder credentials are flagged as available for future use, by including credentialsonfile=1 in the payload, this will also force step-authentication. Click here to learn more about Credentials on File.
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.
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
Where the JWT response includes 3DS status N (indicating the cardholder failed to successfully complete authentication) you should not submit the authorisation request. If you choose to submit the authorisation request, you will receive an error response.
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/threedresponse |
The format of this value is subject to change. We recommend you don't validate this value. | 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
#!/usr/bin/python
import securetrading
stconfig = securetrading.Config()
stconfig.username = "webservices@example.com"
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' => 'webservices@example.com',
'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 webservices@example.com:Password1^ <DOMAIN>/json/ -H "Content-type: application/json" -H "Accept: application/json" -X POST -d '{
"alias":"webservices@example.com",
"version": "1.00",
"request": [{
"requesttypedescriptions": ["AUTH"],
"sitereference": "test_site12345",
"orderreference": "My_Order_123",
"parenttransactionreference": "1-2-345",
"threedresponse": "XXXXX"
}]
}'
{
"alias":"webservices@example.com",
"version":"1.00",
"request":[{
"requesttypedescriptions":["AUTH"],
"sitereference":"test_site12345",
"orderreference":"My_Order_123",
"parenttransactionreference":"1-2-345",
"threedresponse":"XXXXX"
}]
}
<requestblock version="3.67">
<alias>webservices@example.com</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":"webservices@example.com",
"securityresponsepostcode":"2",
"maskedpan":"411111######0211",
"securityresponseaddress":"0",
"issuercountryiso2a":"US",
"settlestatus":"0"
}],
"secrand":"bsZP"
}