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 article covers using the JavaScript Library to process both the 3-D Secure authentication and the Authorisation, but we also support alternative workflows that may be more suited to your needs:
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
- The ACCOUNTCHECK is processed. This performs preliminary checks on customer’s address and security code. (Customer is not yet charged)
- The THREEDQUERY is then processed. This authenticates the customer using 3-D Secure.
- The AUTH 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 RISKDEC is processed. This performs a series of checks on the details submitted by the customer to check for indications fraud may have occurred.
- The ACCOUNTCHECK is processed. This performs preliminary checks on customer’s address and security code. (Customer is not yet charged)
- The THREEDQUERY is then processed. This authenticates the customer using 3-D Secure.
- The AUTH 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 RISKDEC is processed. This performs a series of checks on the details submitted by the customer to check for indications fraud may have occurred.
- The ACCOUNTCHECK is processed. This performs preliminary checks on customer’s address and security code. (Customer is not yet charged)
- The THREEDQUERY is then processed. This authenticates the customer using 3-D Secure.
- The AUTH 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 RISKDEC is processed. This performs a series of checks on the details submitted by the customer to check for indications fraud may have occurred.
- The THREEDQUERY is then processed. This authenticates the customer using 3-D Secure.
- The AUTH 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 RISKDEC is processed. This performs a series of checks on the details submitted by the customer to check for indications fraud may have occurred.
- The THREEDQUERY is then processed. This authenticates the customer using 3-D Secure.
- The AUTH 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 THREEDQUERY is processed. This authenticates the customer using 3-D Secure.
- The ACCOUNTCHECK 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 THREEDQUERY is processed. This authenticates the customer using 3-D Secure.
- The AUTH 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 THREEDQUERY is processed. This authenticates the customer using 3-D Secure.
- The AUTH is then processed. This processes a payment against the customer’s card.
- The RISKDEC 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 THREEDQUERY is processed. This authenticates the customer using 3-D Secure.
- The AUTH 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 THREEDQUERY is processed. This authenticates the customer using 3-D Secure.
- The ACCOUNTCHECK 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
The contents of the response are dependent on whether the customer was subject to more stringent authentication (referred to as step up authentication).
If the transaction is subject to 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 the transaction is subject to frictionless authentication
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.
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 up authentication. Click here to learn more about Credentials on File.
