Card transactions: Payment flows and additional request types

Michael Buckley

September 28, 2023 14:32

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

[“ACCOUNTCHECK”,”THREEDQUERY”,”AUTH”]

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.

Click here to learn more about this request.

Payload example:

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

[“RISKDEC”,”ACCOUNTCHECK”,”THREEDQUERY”,”AUTH”]

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

[“RISKDEC”,”ACCOUNTCHECK”,”THREEDQUERY”,”AUTH”,”SUBSCRIPTION”]

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

[“RISKDEC”,”THREEDQUERY”,”AUTH”]

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.

Click here to learn more about this request.

Payload example:

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

[“RISKDEC”,”THREEDQUERY”,”AUTH”,”SUBSCRIPTION”]

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

[“THREEDQUERY”,”ACCOUNTCHECK”]

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.

Click here to learn more about this request.

Payload example:

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

[“THREEDQUERY”,”AUTH”]

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

[“THREEDQUERY”,”AUTH”,”RISKDEC”]

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.

Click here to learn more about this request.

Payload example:

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

[“THREEDQUERY”,”AUTH”,”SUBSCRIPTION”]

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.

Click here to learn more about this request.

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

[“THREEDQUERY”,”ACCOUNTCHECK”,”SUBSCRIPTION”]

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.

Click here to learn more about this request.

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.

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.

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

[“ACCOUNTCHECK”,”THREEDQUERY”]

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.
After this, you can perform your own back office processes as necessary, then it is your responsibility to process the AUTH 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"
}

[“THREEDQUERY”]

The THREEDQUERY 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 AUTH 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"
}

Handle authentication response and process authorisation

We recommend checking that the errorcode value returned in all responses is “0”, indicating success.

There are two main outcomes described in the sections below. You must read the below and ensure your solution responds accordingly.

Frictionless - Contains gateway response only

Before trusting any value returned in the jwt payload, your system must first verify the signature to ensure the data has not been modified by an unauthorised third party.

Every JWT returned from the SDK should be verified before continuing. We provide a parsing utility in Kotlin to extract the payload field data as part of reviewing the payment response fields:

val response: PaymentTransactionManager.Response = paymentTransactionManager.executeSession(paymentSession)

//Every JWT returned from the SDK should be verified before further usage.
for (jwt in response.responseJwtList) {
  if (!verifyJwtIntegrity(jwt)) {
    throw SecurityException("JWT verification failed!")
  }
}

val parsedResponse = ResponseParser.parse(response.responseJwtList)

//process parsed response

The response JWT consists of three parts separated by dots (“.”), in the following format:

Header.Payload.Signature

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MzMwOTg4NzMsInBheWxvYWQiOnsicmVxdWVzdHJlZmVyZW5jZSI6IlcyNC1wcWJ3aDBuMiIsInZlcnNpb24iOiIxLjAwIiwiand0IjoiZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnBjM01pT2lKM1pXSnpaWEoyYVdObGMwQnRaWEpqYUdGdWRDNWpiMjBpTENKcFlYUWlPakUyTXpNd09UZzROek1zSW5CaGVXeHZZV1FpT25zaVkzVnpkRzl0WlhKMGIzZHVJam9pUW1GdVoyOXlJaXdpWW1sc2JHbHVaM0J2YzNSamIyUmxJam9pVkVVeE1pQXpVMVFpTENKamRYSnlaVzVqZVdsemJ6TmhJam9pUjBKUUlpd2lZM1Z6ZEc5dFpYSndjbVZ0YVhObElqb2lNVElpTENKaWFXeHNhVzVuYkdGemRHNWhiV1VpT2lKT1lXMWxJaXdpYkc5allXeGxJam9pWlc1ZlIwSWlMQ0pqZFhOMGIyMWxjbXhoYzNSdVlXMWxJam9pVG1GdFpTSXNJbUpwYkd4cGJtZGxiV0ZwYkNJNkluUmxjM1JBWlhoaGJYQnNaUzVqYjIwaUxDSmlhV3hzYVc1bmNISmxiV2x6WlNJNklqRXlJaXdpYzJsMFpYSmxabVZ5Wlc1alpTSTZJblJsYzNReElpd2lZV05qYjNWdWRIUjVjR1ZrWlhOamNtbHdkR2x2YmlJNklrVkRUMDBpTENKd1lYSmxiblIwY21GdWMyRmpkR2x2Ym5KbFptVnlaVzVqWlNJNklqSTBMVGt0T0RBd05qRWlMQ0ppYVd4c2FXNW5jM1J5WldWMElqb2lWR1Z6ZENCemRISmxaWFFpTENKeVpYRjFaWE4wZEhsd1pXUmxjMk55YVhCMGFXOXVjeUk2VzEwc0ltTjFjM1J2YldWeWMzUnlaV1YwSWpvaVZHVnpkQ0J6ZEhKbFpYUWlMQ0pqZFhOMGIyMWxjbkJ2YzNSamIyUmxJam9pTVRFeU15SXNJbUpwYkd4cGJtZDBaV3hsY0dodmJtVjBlWEJsSWpvaVRTSXNJbUpoYzJWaGJXOTFiblFpT2lJeE1EQXdJaXdpWW1sc2JHbHVaM1JsYkdWd2FHOXVaU0k2SWpBeE1qTTBJREV4TVRJeU1pSXNJbUpwYkd4cGJtZG1hWEp6ZEc1aGJXVWlPaUpVWlhOMElpd2lZbWxzYkdsdVozUnZkMjRpT2lKQ1lXNW5iM0lpZlgwLkpfVzlGU19MYkVzTXQ0SjhnWUlTSDNQcjNDMl9PUHRQMVd1Nm1MRklON0UiLCJyZXNwb25zZSI6W3sidHJhbnNhY3Rpb25zdGFydGVkdGltZXN0YW1wIjoiMjAyMS0xMC0wMSAxNDozNDozMyIsImN1c3RvbWVyb3V0cHV0IjoiVEhSRUVEUkVESVJFQ1QiLCJsaXZlc3RhdHVzIjoiMCIsIm1lcmNoYW50bmFtZSI6IlRlc3QgVW5pdHRlc3QgU2l0ZSIsImRjY2VuYWJsZWQiOiIwIiwic2V0dGxlZHVlZGF0ZSI6IjIwMjEtMTAtMDEiLCJlcnJvcmNvZGUiOiIwIiwiYWNxdWlyZXJ0cmFuc2FjdGlvbnJlZmVyZW5jZSI6Ilp6eDhxYzQzUEJGQXZGVXdlNDcwIiwidGlkIjoiMjc4ODAwMDAiLCJ0aHJlZWRwYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNUzR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUkyWm1Jd1pETXlZeTA0WVdObUxUUTRNR1l0T1dZeE5DMWxNV0UwT0RjNU9UQmhaV0VpTENKaFkzTlVjbUZ1YzBsRUlqb2lNMlV6TjJZd1pUSXRNVEEyTlMwMFpEUmtMV0ZqTXprdE9XTTBNMll4TkdGaFl6RXpJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJtZXJjaGFudG51bWJlciI6IjAwMDAwMDAwIiwibWVyY2hhbnRjb3VudHJ5aXNvMmEiOiJHQiIsInN0YXR1cyI6IkMiLCJ0cmFuc2FjdGlvbnJlZmVyZW5jZSI6IjI0LTktODAwNjEiLCJ0aHJlZWR2ZXJzaW9uIjoiMi4xLjAiLCJwYXltZW50dHlwZWRlc2NyaXB0aW9uIjoiVklTQSIsImFjc3VybCI6Imh0dHBzOi8vMG1lcmNoYW50YWNzc3RhZy5jYXJkaW5hbGNvbW1lcmNlLmNvbS9NZXJjaGFudEFDU1dlYi9jcmVxLmpzcCIsImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYWNxdWlyZXJyZXNwb25zZWNvZGUiOiIwIiwicmVxdWVzdHR5cGVkZXNjcmlwdGlvbiI6IlRIUkVFRFFVRVJZIiwiaXNzdWVyIjoiU2VjdXJlVHJhZGluZyBUZXN0IElzc3VlcjEiLCJtYXNrZWRwYW4iOiI0MDAwMDAjIyMjIyMxMDkxIiwiZXJyb3JtZXNzYWdlIjoiT2siLCJvcGVyYXRvcm5hbWUiOiJ3ZWJzZXJ2aWNlc0BtZXJjaGFudC5jb20iLCJlbnJvbGxlZCI6IlkiLCJpc3N1ZXJjb3VudHJ5aXNvMmEiOiJaWiIsInNldHRsZXN0YXR1cyI6IjAifV0sInNlY3JhbmQiOiJad0VjIn0sImF1ZCI6IndlYnNlcnZpY2VzQG1lcmNoYW50LmNvbSJ9.lyPo03P1nTQNohqqF3LZdLWnXoaIzgKMzjC14LWhJG8&

{
"iat": 1633098873,
"payload": {
"requestreference": "W24-pqbwh0n2",
"version": "1.00",
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ3ZWJzZXJ2aWNlc0BtZXJjaGFudC5jb20iLCJpYXQiOjE2MzMwOTg4NzMsInBheWxvYWQiOnsiY3VzdG9tZXJ0b3duIjoiQmFuZ29yIiwiYmlsbGluZ3Bvc3Rjb2RlIjoiVEUxMiAzU1QiLCJjdXJyZW5jeWlzbzNhIjoiR0JQIiwiY3VzdG9tZXJwcmVtaXNlIjoiMTIiLCJiaWxsaW5nbGFzdG5hbWUiOiJOYW1lIiwibG9jYWxlIjoiZW5fR0IiLCJjdXN0b21lcmxhc3RuYW1lIjoiTmFtZSIsImJpbGxpbmdlbWFpbCI6InRlc3RAZXhhbXBsZS5jb20iLCJiaWxsaW5ncHJlbWlzZSI6IjEyIiwic2l0ZXJlZmVyZW5jZSI6InRlc3QxIiwiYWNjb3VudHR5cGVkZXNjcmlwdGlvbiI6IkVDT00iLCJwYXJlbnR0cmFuc2FjdGlvbnJlZmVyZW5jZSI6IjI0LTktODAwNjEiLCJiaWxsaW5nc3RyZWV0IjoiVGVzdCBzdHJlZXQiLCJyZXF1ZXN0dHlwZWRlc2NyaXB0aW9ucyI6W10sImN1c3RvbWVyc3RyZWV0IjoiVGVzdCBzdHJlZXQiLCJjdXN0b21lcnBvc3Rjb2RlIjoiMTEyMyIsImJpbGxpbmd0ZWxlcGhvbmV0eXBlIjoiTSIsImJhc2VhbW91bnQiOiIxMDAwIiwiYmlsbGluZ3RlbGVwaG9uZSI6IjAxMjM0IDExMTIyMiIsImJpbGxpbmdmaXJzdG5hbWUiOiJUZXN0IiwiYmlsbGluZ3Rvd24iOiJCYW5nb3IifX0.J_W9FS_LbEsMt4J8gYISH3Pr3C2_OPtP1Wu6mLFIN7E",
"response": [
{
"accounttypedescription": "ECOM",
"acquirerresponsecode": "0",
"acquirertransactionreference": "Zzx8qc43PBFAvFUwe470",
"acsurl": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",
"customeroutput": "THREEDREDIRECT",
"dccenabled": "0",
"enrolled": "Y",
"errorcode": "0",
"errormessage": "Ok",
"issuer": "Test Issuer",
"issuercountryiso2a": "ZZ",
"livestatus": "0",
"maskedpan": "400000######1091",
"merchantcountryiso2a": "GB",
"merchantname": "Test merchant",
"merchantnumber": "00000000",
"operatorname": "webservices@merchant.com",
"paymenttypedescription": "VISA",
"requesttypedescription": "THREEDQUERY",
"settleduedate": "2021-10-01",
"settlestatus": "0",
"status": "C",
"threedpayload": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI2ZmIwZDMyYy04YWNmLTQ4MGYtOWYxNC1lMWE0ODc5OTBhZWEiLCJhY3NUcmFuc0lEIjoiM2UzN2YwZTItMTA2NS00ZDRkLWFjMzktOWM0M2YxNGFhYzEzIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0",
"threedversion": "2.1.0",
"tid": "00000000",
"transactionreference": "24-9-80061",
"transactionstartedtimestamp": "2021-10-01 14:34:33"
}
],
"secrand": "ZwEc"
},
"aud": "webservices@merchant.com"
}

Before you can trust the response, you need to check the signature returned matches the value expected. If not, it may have been modified by an unauthorised party.

The library you chose earlier to generate and verify the JWT included on your payment form can also be used to verify the JWT returned.

How this works

The signature is hashed using SHA-256, and as such, cannot be decoded. This means that to check the signature is correct, it will need to be re-calculated using the header and payload returned.
Providing the same secret is used during this process, the recalculated signature should match that returned in the response JWT. In summary:

Base64URL decode JWT header
Base64URL decode JWT payload
Re-generate the signature by re-encoding the header, the payload and signing them with the secret.

Once this process has been completed, we recommend ensuring the errorcode value returned in the response is “0”, indicating success.

Submit AUTH request using Webservices API

After the EMV 3DS authentication has been performed, you will need to submit an AUTH request to Trust Payments using our Webservices API to in order to process the payment.

If you haven't done so already, we recommend reading our Getting started documentation to learn how to process a basic request with our Webservices API.

Click here to open this in a new tab.

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.

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.

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": "24-9-80061"
}

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' => '24-9-80061'
);

$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": "24-9-80061"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "requesttypedescriptions":["AUTH"],
    "sitereference":"test_site12345",
    "orderreference":"My_Order_123",
    "parenttransactionreference":"24-9-80061"
  }]
}

<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>24-9-80061</parenttransactionreference>
    </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.

Click here to learn about the checks you should perform on responses returned from Trust Payments to ensure the transaction was processed successfully.

{
  "requestreference":"W23-n68rw97k",
  "version":"1.00",
  "response":[{
    "accounttypedescription":"ECOM",
    "acquirerresponsecode":"00",
    "authcode":"TEST",
    "baseamount":"1050",
    "cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=",
    "currencyiso3a":"GBP",
    "dccenabled":"0",
    "eci":"05",
    "enrolled":"Y",
    "errorcode":"0",
    "errormessage":"Ok",
    "issuer":"Test Issuer",
    "issuercountryiso2a":"US",
    "livestatus":"0",
    "maskedpan":"400000######1091",
    "merchantcountryiso2a":"GB",
    "merchantname":"Test Merchant",
    "merchantnumber":"00000000",
    "operatorname":"webservices@example.com",
    "parenttransactionreference":"24-9-80061",
    "paymenttypedescription":"VISA",
    "requesttypedescription":"AUTH",
    "securityresponseaddress":"0",
    "securityresponsepostcode":"2",
    "securityresponsesecuritycode":"2",
    "settleduedate":"2021-10-01",
    "settlestatus":"0",
    "status":"Y",
    "tid":"00000000",
    "transactionreference":"24-9-80061",
    "transactionstartedtimestamp":"2021-10-01 14:34:35",
    "xid":"NmVxNGtsTDBkSVJzcmwrSnEyMFc="
  }],
  "secrand":"bsZP"
}

Step-up - Contains gateway response and step-up authentication result

Before trusting any value returned in the jwt payload, your system must first verify the signature to ensure the data has not been modified by an unauthorised third party.

Every JWT returned from the SDK should be verified before continuing. We provide a parsing utility in Kotlin to extract the payload field data as part of reviewing the payment response fields:

val response: PaymentTransactionManager.Response = paymentTransactionManager.executeSession(paymentSession)

//Every JWT returned from the SDK should be verified before further usage.
for (jwt in response.responseJwtList) {
  if (!verifyJwtIntegrity(jwt)) {
    throw SecurityException("JWT verification failed!")
  }
}

val parsedResponse = ResponseParser.parse(response.responseJwtList)

//process parsed response

The response JWT consists of three parts separated by dots (“.”), in the following format:

Header.Payload.Signature

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpYXQiOjE2MzMwOTg4NzMsInBheWxvYWQiOnsicmVxdWVzdHJlZmVyZW5jZSI6IlcyNC1wcWJ3aDBuMiIsInZlcnNpb24iOiIxLjAwIiwiand0IjoiZXlKaGJHY2lPaUpJVXpJMU5pSXNJblI1Y0NJNklrcFhWQ0o5LmV5SnBjM01pT2lKM1pXSnpaWEoyYVdObGMwQnRaWEpqYUdGdWRDNWpiMjBpTENKcFlYUWlPakUyTXpNd09UZzROek1zSW5CaGVXeHZZV1FpT25zaVkzVnpkRzl0WlhKMGIzZHVJam9pUW1GdVoyOXlJaXdpWW1sc2JHbHVaM0J2YzNSamIyUmxJam9pVkVVeE1pQXpVMVFpTENKamRYSnlaVzVqZVdsemJ6TmhJam9pUjBKUUlpd2lZM1Z6ZEc5dFpYSndjbVZ0YVhObElqb2lNVElpTENKaWFXeHNhVzVuYkdGemRHNWhiV1VpT2lKT1lXMWxJaXdpYkc5allXeGxJam9pWlc1ZlIwSWlMQ0pqZFhOMGIyMWxjbXhoYzNSdVlXMWxJam9pVG1GdFpTSXNJbUpwYkd4cGJtZGxiV0ZwYkNJNkluUmxjM1JBWlhoaGJYQnNaUzVqYjIwaUxDSmlhV3hzYVc1bmNISmxiV2x6WlNJNklqRXlJaXdpYzJsMFpYSmxabVZ5Wlc1alpTSTZJblJsYzNReElpd2lZV05qYjNWdWRIUjVjR1ZrWlhOamNtbHdkR2x2YmlJNklrVkRUMDBpTENKd1lYSmxiblIwY21GdWMyRmpkR2x2Ym5KbFptVnlaVzVqWlNJNklqSTBMVGt0T0RBd05qRWlMQ0ppYVd4c2FXNW5jM1J5WldWMElqb2lWR1Z6ZENCemRISmxaWFFpTENKeVpYRjFaWE4wZEhsd1pXUmxjMk55YVhCMGFXOXVjeUk2VzEwc0ltTjFjM1J2YldWeWMzUnlaV1YwSWpvaVZHVnpkQ0J6ZEhKbFpYUWlMQ0pqZFhOMGIyMWxjbkJ2YzNSamIyUmxJam9pTVRFeU15SXNJbUpwYkd4cGJtZDBaV3hsY0dodmJtVjBlWEJsSWpvaVRTSXNJbUpoYzJWaGJXOTFiblFpT2lJeE1EQXdJaXdpWW1sc2JHbHVaM1JsYkdWd2FHOXVaU0k2SWpBeE1qTTBJREV4TVRJeU1pSXNJbUpwYkd4cGJtZG1hWEp6ZEc1aGJXVWlPaUpVWlhOMElpd2lZbWxzYkdsdVozUnZkMjRpT2lKQ1lXNW5iM0lpZlgwLkpfVzlGU19MYkVzTXQ0SjhnWUlTSDNQcjNDMl9PUHRQMVd1Nm1MRklON0UiLCJyZXNwb25zZSI6W3sidHJhbnNhY3Rpb25zdGFydGVkdGltZXN0YW1wIjoiMjAyMS0xMC0wMSAxNDozNDozMyIsImN1c3RvbWVyb3V0cHV0IjoiVEhSRUVEUkVESVJFQ1QiLCJsaXZlc3RhdHVzIjoiMCIsIm1lcmNoYW50bmFtZSI6IlRlc3QgVW5pdHRlc3QgU2l0ZSIsImRjY2VuYWJsZWQiOiIwIiwic2V0dGxlZHVlZGF0ZSI6IjIwMjEtMTAtMDEiLCJlcnJvcmNvZGUiOiIwIiwiYWNxdWlyZXJ0cmFuc2FjdGlvbnJlZmVyZW5jZSI6Ilp6eDhxYzQzUEJGQXZGVXdlNDcwIiwidGlkIjoiMjc4ODAwMDAiLCJ0aHJlZWRwYXlsb2FkIjoiZXlKdFpYTnpZV2RsVkhsd1pTSTZJa05TWlhFaUxDSnRaWE56WVdkbFZtVnljMmx2YmlJNklqSXVNUzR3SWl3aWRHaHlaV1ZFVTFObGNuWmxjbFJ5WVc1elNVUWlPaUkyWm1Jd1pETXlZeTA0WVdObUxUUTRNR1l0T1dZeE5DMWxNV0UwT0RjNU9UQmhaV0VpTENKaFkzTlVjbUZ1YzBsRUlqb2lNMlV6TjJZd1pUSXRNVEEyTlMwMFpEUmtMV0ZqTXprdE9XTTBNMll4TkdGaFl6RXpJaXdpWTJoaGJHeGxibWRsVjJsdVpHOTNVMmw2WlNJNklqQXlJbjAiLCJtZXJjaGFudG51bWJlciI6IjAwMDAwMDAwIiwibWVyY2hhbnRjb3VudHJ5aXNvMmEiOiJHQiIsInN0YXR1cyI6IkMiLCJ0cmFuc2FjdGlvbnJlZmVyZW5jZSI6IjI0LTktODAwNjEiLCJ0aHJlZWR2ZXJzaW9uIjoiMi4xLjAiLCJwYXltZW50dHlwZWRlc2NyaXB0aW9uIjoiVklTQSIsImFjc3VybCI6Imh0dHBzOi8vMG1lcmNoYW50YWNzc3RhZy5jYXJkaW5hbGNvbW1lcmNlLmNvbS9NZXJjaGFudEFDU1dlYi9jcmVxLmpzcCIsImFjY291bnR0eXBlZGVzY3JpcHRpb24iOiJFQ09NIiwiYWNxdWlyZXJyZXNwb25zZWNvZGUiOiIwIiwicmVxdWVzdHR5cGVkZXNjcmlwdGlvbiI6IlRIUkVFRFFVRVJZIiwiaXNzdWVyIjoiU2VjdXJlVHJhZGluZyBUZXN0IElzc3VlcjEiLCJtYXNrZWRwYW4iOiI0MDAwMDAjIyMjIyMxMDkxIiwiZXJyb3JtZXNzYWdlIjoiT2siLCJvcGVyYXRvcm5hbWUiOiJ3ZWJzZXJ2aWNlc0BtZXJjaGFudC5jb20iLCJlbnJvbGxlZCI6IlkiLCJpc3N1ZXJjb3VudHJ5aXNvMmEiOiJaWiIsInNldHRsZXN0YXR1cyI6IjAifV0sInNlY3JhbmQiOiJad0VjIn0sImF1ZCI6IndlYnNlcnZpY2VzQG1lcmNoYW50LmNvbSJ9.lyPo03P1nTQNohqqF3LZdLWnXoaIzgKMzjC14LWhJG8&

{
"iat": 1633098873,
"payload": {
"requestreference": "W24-pqbwh0n2",
"version": "1.00",
"jwt": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJ3ZWJzZXJ2aWNlc0BtZXJjaGFudC5jb20iLCJpYXQiOjE2MzMwOTg4NzMsInBheWxvYWQiOnsiY3VzdG9tZXJ0b3duIjoiQmFuZ29yIiwiYmlsbGluZ3Bvc3Rjb2RlIjoiVEUxMiAzU1QiLCJjdXJyZW5jeWlzbzNhIjoiR0JQIiwiY3VzdG9tZXJwcmVtaXNlIjoiMTIiLCJiaWxsaW5nbGFzdG5hbWUiOiJOYW1lIiwibG9jYWxlIjoiZW5fR0IiLCJjdXN0b21lcmxhc3RuYW1lIjoiTmFtZSIsImJpbGxpbmdlbWFpbCI6InRlc3RAZXhhbXBsZS5jb20iLCJiaWxsaW5ncHJlbWlzZSI6IjEyIiwic2l0ZXJlZmVyZW5jZSI6InRlc3QxIiwiYWNjb3VudHR5cGVkZXNjcmlwdGlvbiI6IkVDT00iLCJwYXJlbnR0cmFuc2FjdGlvbnJlZmVyZW5jZSI6IjI0LTktODAwNjEiLCJiaWxsaW5nc3RyZWV0IjoiVGVzdCBzdHJlZXQiLCJyZXF1ZXN0dHlwZWRlc2NyaXB0aW9ucyI6W10sImN1c3RvbWVyc3RyZWV0IjoiVGVzdCBzdHJlZXQiLCJjdXN0b21lcnBvc3Rjb2RlIjoiMTEyMyIsImJpbGxpbmd0ZWxlcGhvbmV0eXBlIjoiTSIsImJhc2VhbW91bnQiOiIxMDAwIiwiYmlsbGluZ3RlbGVwaG9uZSI6IjAxMjM0IDExMTIyMiIsImJpbGxpbmdmaXJzdG5hbWUiOiJUZXN0IiwiYmlsbGluZ3Rvd24iOiJCYW5nb3IifX0.J_W9FS_LbEsMt4J8gYISH3Pr3C2_OPtP1Wu6mLFIN7E",
"response": [
{
"accounttypedescription": "ECOM",
"acquirerresponsecode": "0",
"acquirertransactionreference": "Zzx8qc43PBFAvFUwe470",
"acsurl": "https://0merchantacsstag.cardinalcommerce.com/MerchantACSWeb/creq.jsp",
"customeroutput": "THREEDREDIRECT",
"dccenabled": "0",
"enrolled": "Y",
"errorcode": "0",
"errormessage": "Ok",
"issuer": "Test Issuer",
"issuercountryiso2a": "ZZ",
"livestatus": "0",
"maskedpan": "400000######1091",
"merchantcountryiso2a": "GB",
"merchantname": "Test merchant",
"merchantnumber": "00000000",
"operatorname": "webservices@merchant.com",
"paymenttypedescription": "VISA",
"requesttypedescription": "THREEDQUERY",
"settleduedate": "2021-10-01",
"settlestatus": "0",
"status": "C",
"threedpayload": "eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiI2ZmIwZDMyYy04YWNmLTQ4MGYtOWYxNC1lMWE0ODc5OTBhZWEiLCJhY3NUcmFuc0lEIjoiM2UzN2YwZTItMTA2NS00ZDRkLWFjMzktOWM0M2YxNGFhYzEzIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjAyIn0",
"threedversion": "2.1.0",
"tid": "00000000",
"transactionreference": "24-9-80061",
"transactionstartedtimestamp": "2021-10-01 14:34:33"

}
],
"secrand": "ZwEc"
},
"aud": "webservices@merchant.com"
}

Before you can trust the response, you need to check the signature returned matches the value expected. If not, it may have been modified by an unauthorised party.

The library you chose earlier to generate and verify the JWT included on your payment form can also be used to verify the JWT returned.

How this works

Base64URL decode JWT header
Base64URL decode JWT payload
Re-generate the signature by re-encoding the header, the payload and signing them with the secret.

Once this process has been completed, we recommend ensuring the errorcode value returned in the response is “0”, indicating success.

Because the customer was subject to challenge authentication, the signature of the threedresponse will also be returned in the response. The threedresponse must be included in the AUTH request. The following is an example of a threedresponse:

eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1YzEyODg0NWMxMWI5MjIwZGMwNDZlOGUiLCJpYXQiOjE2MzMwOTg4NzcsImV4cCI6MTYzMzEwNjA3NywianRpIjoiNGQyMjA5NGMtZjY3Mi00YTRjLWIwMTktYjhjZDY2ZDM0MzBiIiwiQ29uc3VtZXJTZXNzaW9uSWQiOiIwXzU2OTgwMzA1LTk1ZmQtNDNmOC05NzRlLTQ0NmFhMGU4MjgzNCIsIlJlZmVyZW5jZUlkIjoiMjQtMmJhNzBjYTMxZDMyYzI0ZGU4OGEzNTE4ZjE0NTMzY2FlOGViMjhhZjRhNDVlODBiODQwNmZkNGE4MTRjZmI0YSIsImF1ZCI6IjI0LTJiYTcwY2EzMWQzMmMyNGRlODhhMzUxOGYxNDUzM2NhZThlYjI4YWY0YTQ1ZTgwYjg0MDZmZDRhODE0Y2ZiNGEiLCJQYXlsb2FkIjp7IlZhbGlkYXRlZCI6dHJ1ZSwiUGF5bWVudCI6eyJUeXBlIjoiQ0NBIiwiUHJvY2Vzc29yVHJhbnNhY3Rpb25JZCI6Ilp6eDhxYzQzUEJGQXZGVXdlNDcwIiwiRXh0ZW5kZWREYXRhIjp7IkFtb3VudCI6IjEwMDAiLCJDQVZWIjoiTVRJek5EVTJOemc1TURFeU16UTFOamM0T1RBXHUwMDNkIiwiQ3VycmVuY3lDb2RlIjoiODI2IiwiRUNJRmxhZyI6IjA1IiwiVGhyZWVEU1ZlcnNpb24iOiIyLjEuMCIsIlBBUmVzU3RhdHVzIjoiWSIsIlNpZ25hdHVyZVZlcmlmaWNhdGlvbiI6IlkifX0sIkFjdGlvbkNvZGUiOiJTVUNDRVNTIiwiRXJyb3JOdW1iZXIiOjAsIkVycm9yRGVzY3JpcHRpb24iOiJTdWNjZXNzIn19.A5t9bo59kFKehQIwjaqQ2UAAqEdVlBCbI2ZbEFvUz98

Submit AUTH request using Webservices API

After the EMV 3DS authentication has been performed, you will need to submit an AUTH request to Trust Payments using our Webservices API to in order to process the payment.

If you haven't done so already, we recommend reading our Getting started documentation to learn how to process a basic request with our Webservices API.

Click here to open this in a new tab.

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/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 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 returned in the authentication 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": "24-9-80061",
  "threedresponse": "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1YzEyODg0NWMxMWI5MjIwZGMwNDZlOGUiLCJpYXQiOjE2MzMwOTg4NzcsImV4cCI6MTYzMzEwNjA3NywianRpIjoiNGQyMjA5NGMtZjY3Mi00YTRjLWIwMTktYjhjZDY2ZDM0MzBiIiwiQ29uc3VtZXJTZXNzaW9uSWQiOiIwXzU2OTgwMzA1LTk1ZmQtNDNmOC05NzRlLTQ0NmFhMGU4MjgzNCIsIlJlZmVyZW5jZUlkIjoiMjQtMmJhNzBjYTMxZDMyYzI0ZGU4OGEzNTE4ZjE0NTMzY2FlOGViMjhhZjRhNDVlODBiODQwNmZkNGE4MTRjZmI0YSIsImF1ZCI6IjI0LTJiYTcwY2EzMWQzMmMyNGRlODhhMzUxOGYxNDUzM2NhZThlYjI4YWY0YTQ1ZTgwYjg0MDZmZDRhODE0Y2ZiNGEiLCJQYXlsb2FkIjp7IlZhbGlkYXRlZCI6dHJ1ZSwiUGF5bWVudCI6eyJUeXBlIjoiQ0NBIiwiUHJvY2Vzc29yVHJhbnNhY3Rpb25JZCI6Ilp6eDhxYzQzUEJGQXZGVXdlNDcwIiwiRXh0ZW5kZWREYXRhIjp7IkFtb3VudCI6IjEwMDAiLCJDQVZWIjoiTVRJek5EVTJOemc1TURFeU16UTFOamM0T1RBXHUwMDNkIiwiQ3VycmVuY3lDb2RlIjoiODI2IiwiRUNJRmxhZyI6IjA1IiwiVGhyZWVEU1ZlcnNpb24iOiIyLjEuMCIsIlBBUmVzU3RhdHVzIjoiWSIsIlNpZ25hdHVyZVZlcmlmaWNhdGlvbiI6IlkifX0sIkFjdGlvbkNvZGUiOiJTVUNDRVNTIiwiRXJyb3JOdW1iZXIiOjAsIkVycm9yRGVzY3JpcHRpb24iOiJTdWNjZXNzIn19.A5t9bo59kFKehQIwjaqQ2UAAqEdVlBCbI2ZbEFvUz98"
}

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' => '24-9-80061',
  'threedresponse' => 'eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1YzEyODg0NWMxMWI5MjIwZGMwNDZlOGUiLCJpYXQiOjE2MzMwOTg4NzcsImV4cCI6MTYzMzEwNjA3NywianRpIjoiNGQyMjA5NGMtZjY3Mi00YTRjLWIwMTktYjhjZDY2ZDM0MzBiIiwiQ29uc3VtZXJTZXNzaW9uSWQiOiIwXzU2OTgwMzA1LTk1ZmQtNDNmOC05NzRlLTQ0NmFhMGU4MjgzNCIsIlJlZmVyZW5jZUlkIjoiMjQtMmJhNzBjYTMxZDMyYzI0ZGU4OGEzNTE4ZjE0NTMzY2FlOGViMjhhZjRhNDVlODBiODQwNmZkNGE4MTRjZmI0YSIsImF1ZCI6IjI0LTJiYTcwY2EzMWQzMmMyNGRlODhhMzUxOGYxNDUzM2NhZThlYjI4YWY0YTQ1ZTgwYjg0MDZmZDRhODE0Y2ZiNGEiLCJQYXlsb2FkIjp7IlZhbGlkYXRlZCI6dHJ1ZSwiUGF5bWVudCI6eyJUeXBlIjoiQ0NBIiwiUHJvY2Vzc29yVHJhbnNhY3Rpb25JZCI6Ilp6eDhxYzQzUEJGQXZGVXdlNDcwIiwiRXh0ZW5kZWREYXRhIjp7IkFtb3VudCI6IjEwMDAiLCJDQVZWIjoiTVRJek5EVTJOemc1TURFeU16UTFOamM0T1RBXHUwMDNkIiwiQ3VycmVuY3lDb2RlIjoiODI2IiwiRUNJRmxhZyI6IjA1IiwiVGhyZWVEU1ZlcnNpb24iOiIyLjEuMCIsIlBBUmVzU3RhdHVzIjoiWSIsIlNpZ25hdHVyZVZlcmlmaWNhdGlvbiI6IlkifX0sIkFjdGlvbkNvZGUiOiJTVUNDRVNTIiwiRXJyb3JOdW1iZXIiOjAsIkVycm9yRGVzY3JpcHRpb24iOiJTdWNjZXNzIn19.A5t9bo59kFKehQIwjaqQ2UAAqEdVlBCbI2ZbEFvUz98'
);

$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": "24-9-80061",
    "threedresponse": "eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1YzEyODg0NWMxMWI5MjIwZGMwNDZlOGUiLCJpYXQiOjE2MzMwOTg4NzcsImV4cCI6MTYzMzEwNjA3NywianRpIjoiNGQyMjA5NGMtZjY3Mi00YTRjLWIwMTktYjhjZDY2ZDM0MzBiIiwiQ29uc3VtZXJTZXNzaW9uSWQiOiIwXzU2OTgwMzA1LTk1ZmQtNDNmOC05NzRlLTQ0NmFhMGU4MjgzNCIsIlJlZmVyZW5jZUlkIjoiMjQtMmJhNzBjYTMxZDMyYzI0ZGU4OGEzNTE4ZjE0NTMzY2FlOGViMjhhZjRhNDVlODBiODQwNmZkNGE4MTRjZmI0YSIsImF1ZCI6IjI0LTJiYTcwY2EzMWQzMmMyNGRlODhhMzUxOGYxNDUzM2NhZThlYjI4YWY0YTQ1ZTgwYjg0MDZmZDRhODE0Y2ZiNGEiLCJQYXlsb2FkIjp7IlZhbGlkYXRlZCI6dHJ1ZSwiUGF5bWVudCI6eyJUeXBlIjoiQ0NBIiwiUHJvY2Vzc29yVHJhbnNhY3Rpb25JZCI6Ilp6eDhxYzQzUEJGQXZGVXdlNDcwIiwiRXh0ZW5kZWREYXRhIjp7IkFtb3VudCI6IjEwMDAiLCJDQVZWIjoiTVRJek5EVTJOemc1TURFeU16UTFOamM0T1RBXHUwMDNkIiwiQ3VycmVuY3lDb2RlIjoiODI2IiwiRUNJRmxhZyI6IjA1IiwiVGhyZWVEU1ZlcnNpb24iOiIyLjEuMCIsIlBBUmVzU3RhdHVzIjoiWSIsIlNpZ25hdHVyZVZlcmlmaWNhdGlvbiI6IlkifX0sIkFjdGlvbkNvZGUiOiJTVUNDRVNTIiwiRXJyb3JOdW1iZXIiOjAsIkVycm9yRGVzY3JpcHRpb24iOiJTdWNjZXNzIn19.A5t9bo59kFKehQIwjaqQ2UAAqEdVlBCbI2ZbEFvUz98"
  }]
}'

{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "requesttypedescriptions":["AUTH"],
    "sitereference":"test_site12345",
    "orderreference":"My_Order_123",
    "parenttransactionreference":"24-9-80061",
    "threedresponse":"eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1YzEyODg0NWMxMWI5MjIwZGMwNDZlOGUiLCJpYXQiOjE2MzMwOTg4NzcsImV4cCI6MTYzMzEwNjA3NywianRpIjoiNGQyMjA5NGMtZjY3Mi00YTRjLWIwMTktYjhjZDY2ZDM0MzBiIiwiQ29uc3VtZXJTZXNzaW9uSWQiOiIwXzU2OTgwMzA1LTk1ZmQtNDNmOC05NzRlLTQ0NmFhMGU4MjgzNCIsIlJlZmVyZW5jZUlkIjoiMjQtMmJhNzBjYTMxZDMyYzI0ZGU4OGEzNTE4ZjE0NTMzY2FlOGViMjhhZjRhNDVlODBiODQwNmZkNGE4MTRjZmI0YSIsImF1ZCI6IjI0LTJiYTcwY2EzMWQzMmMyNGRlODhhMzUxOGYxNDUzM2NhZThlYjI4YWY0YTQ1ZTgwYjg0MDZmZDRhODE0Y2ZiNGEiLCJQYXlsb2FkIjp7IlZhbGlkYXRlZCI6dHJ1ZSwiUGF5bWVudCI6eyJUeXBlIjoiQ0NBIiwiUHJvY2Vzc29yVHJhbnNhY3Rpb25JZCI6Ilp6eDhxYzQzUEJGQXZGVXdlNDcwIiwiRXh0ZW5kZWREYXRhIjp7IkFtb3VudCI6IjEwMDAiLCJDQVZWIjoiTVRJek5EVTJOemc1TURFeU16UTFOamM0T1RBXHUwMDNkIiwiQ3VycmVuY3lDb2RlIjoiODI2IiwiRUNJRmxhZyI6IjA1IiwiVGhyZWVEU1ZlcnNpb24iOiIyLjEuMCIsIlBBUmVzU3RhdHVzIjoiWSIsIlNpZ25hdHVyZVZlcmlmaWNhdGlvbiI6IlkifX0sIkFjdGlvbkNvZGUiOiJTVUNDRVNTIiwiRXJyb3JOdW1iZXIiOjAsIkVycm9yRGVzY3JpcHRpb24iOiJTdWNjZXNzIn19.A5t9bo59kFKehQIwjaqQ2UAAqEdVlBCbI2ZbEFvUz98"
  }]
}

<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>24-9-80061</parenttransactionreference>
      <threedresponse>eyJhbGciOiJIUzI1NiJ9.eyJpc3MiOiI1YzEyODg0NWMxMWI5MjIwZGMwNDZlOGUiLCJpYXQiOjE2MzMwOTg4NzcsImV4cCI6MTYzMzEwNjA3NywianRpIjoiNGQyMjA5NGMtZjY3Mi00YTRjLWIwMTktYjhjZDY2ZDM0MzBiIiwiQ29uc3VtZXJTZXNzaW9uSWQiOiIwXzU2OTgwMzA1LTk1ZmQtNDNmOC05NzRlLTQ0NmFhMGU4MjgzNCIsIlJlZmVyZW5jZUlkIjoiMjQtMmJhNzBjYTMxZDMyYzI0ZGU4OGEzNTE4ZjE0NTMzY2FlOGViMjhhZjRhNDVlODBiODQwNmZkNGE4MTRjZmI0YSIsImF1ZCI6IjI0LTJiYTcwY2EzMWQzMmMyNGRlODhhMzUxOGYxNDUzM2NhZThlYjI4YWY0YTQ1ZTgwYjg0MDZmZDRhODE0Y2ZiNGEiLCJQYXlsb2FkIjp7IlZhbGlkYXRlZCI6dHJ1ZSwiUGF5bWVudCI6eyJUeXBlIjoiQ0NBIiwiUHJvY2Vzc29yVHJhbnNhY3Rpb25JZCI6Ilp6eDhxYzQzUEJGQXZGVXdlNDcwIiwiRXh0ZW5kZWREYXRhIjp7IkFtb3VudCI6IjEwMDAiLCJDQVZWIjoiTVRJek5EVTJOemc1TURFeU16UTFOamM0T1RBXHUwMDNkIiwiQ3VycmVuY3lDb2RlIjoiODI2IiwiRUNJRmxhZyI6IjA1IiwiVGhyZWVEU1ZlcnNpb24iOiIyLjEuMCIsIlBBUmVzU3RhdHVzIjoiWSIsIlNpZ25hdHVyZVZlcmlmaWNhdGlvbiI6IlkifX0sIkFjdGlvbkNvZGUiOiJTVUNDRVNTIiwiRXJyb3JOdW1iZXIiOjAsIkVycm9yRGVzY3JpcHRpb24iOiJTdWNjZXNzIn19.A5t9bo59kFKehQIwjaqQ2UAAqEdVlBCbI2ZbEFvUz98</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.

Click here to learn about the checks you should perform on responses returned from Trust Payments to ensure the transaction was processed successfully.

{
  "requestreference":"W23-n68rw97k",
  "version":"1.00",
  "response":[{
    "accounttypedescription":"ECOM",
    "acquirerresponsecode":"00",
    "authcode":"TEST",
    "baseamount":"1050",
    "cavv":"Q0FWVkNBVlZDQVZWQ0FWVkNBVlY=",
    "currencyiso3a":"GBP",
    "dccenabled":"0",
    "eci":"05",
    "enrolled":"Y",
    "errorcode":"0",
    "errormessage":"Ok",
    "issuer":"Test Issuer",
    "issuercountryiso2a":"US",
    "livestatus":"0",
    "maskedpan":"400000######1091",
    "merchantcountryiso2a":"GB",
    "merchantname":"Test Merchant",
    "merchantnumber":"00000000",
    "operatorname":"webservices@example.com",
    "parenttransactionreference":"24-9-80061",
    "paymenttypedescription":"VISA",
    "requesttypedescription":"AUTH",
    "securityresponseaddress":"0",
    "securityresponsepostcode":"2",
    "securityresponsesecuritycode":"2",
    "settleduedate":"2021-10-01",
    "settlestatus":"0",
    "status":"Y",
    "tid":"00000000",
    "transactionreference":"24-9-80061",
    "transactionstartedtimestamp":"2021-10-01 14:34:35",
    "xid":"NmVxNGtsTDBkSVJzcmwrSnEyMFc="
  }],
  "secrand":"bsZP"
}

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

Supported request types

Handling the JWT response

Forcing step up (challenge) authentication

2. Mobile SDK processes 3-D Secure authentication, then Authorisation processed through Webservices API

Supported request types

Handle authentication response and process authorisation

Submit AUTH request using Webservices API

Authorisation field specification

Code example

Handle the Authorisation response

Submit AUTH request using Webservices API

Authorisation field specification

Code example

Handle the Authorisation response

Articles in this section