1. TRU Security   
  2. 3DS API

Testing Challenge flow - Walkthrough

​  Last updated: 

 

 

The following are two example workflows for challenge transactions processed using our 3DS API:

Please ensure your system can process the requests documented and handle the responses returned.

  To test your application locally, you will need to run your test application with your IPv4 address rather than localhost. After performing a lookup of your IPv4 address, you will need to replace localhost in your browser with the IP address retrieved.

  We recommend reading the below in conjunction with our high-level overview flow.
Click here to open this in a new tab.

 

             

 

Example 1 - Challenge - No threedmethodurl

 

Step 1. THREEDLOOKUP

THREEDLOOKUP Request Example

The following is an example of a THREEDLOOKUP request submitted using the Webservices API:

Raw JSON Raw XML 
{
  "alias": "webservices@example.com",
  "version": "1.00",
  "request": [{
    "accounttypedescription": "ECOM",
    "baseamount": "1050",
    "currencyiso3a": "GBP",
    "expirydate": "01/2038",
    "pan": "4900490000000667",
    "requesttypedescription": "THREEDLOOKUP",
    "sitereference": "test_3dsapi12345"
  }]
}

  THREEDLOOKUP Request Field Specification

Click here to open the field specification in a new tab.

 

THREEDLOOKUP Response Example

The following is an example of a THREEDLOOKUP response returned:

Raw JSON Raw XML 
{
  "requestreference": "W57-cnk4dbg4",
  "response": [{
    "cachetoken": "eyJkYXRhY2VudGVydXJsIjogImh0dHBzOi8vd2Vic2VydmljZXMuc2VjdXJldHJhZGluZy5uZXQiLCAiY2FjaGV0b2tlbiI6ICI1Ny01ODRlOWMwNDliZTczZTIxNGNkZTU1MTk0NDQ3OWY4MGNhMzg3OGVmZTI1N2EzN2MwMWRmOTc1ZWRlYjI3YTBjIn0=",
    "debtrepayment": "0",
    "errorcode": "0",
    "errormessage": "Ok",
    "maskedpan": "490049######0667",
    "paymenttypedescription": "DELTA",
    "requesttypedescription": "THREEDLOOKUP",
    "threedstransactionid": "cebcb773-3aa1-4bfa-a959-135aa50bb760",
    "threedversion": "2.2.0",
    "transactionstartedtimestamp": "2022-06-14 15:34:18"
  }],
  "secrand": "E9DXCCLNL",
  "version": "1.00"
}

  THREEDLOOKUP Response Field Specification

Click here to open the field specification in a new tab.

 

             

 

Step 2. Method URL

  Only perform this step if threedmethodurl is returned in the THREEDLOOKUP response. Seeing as we are not returned the field in this flow, we will proceed to step 3.

 

             

 

Step 3. THREEDQUERY

  It may not be possible to capture the customerip and accept (HTTP accept-header) from within the browser itself, therefore you'll need to configure an endpoint on your server, which will allow you to perform a GET request to return the customerip and accept values back to browser.

 

THREEDQUERY Request Example

The following is an example of a THREEDQUERY request submitted using the Webservices API:

Raw JSON Raw XML 
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "accept": "text/html,*/*",
    "accounttypedescription": "ECOM",
    "acquirerbin": "408912",
    "baseamount": "1050",
    "browsercolordepth": "24",
    "browserjavaenabled": "false",
    "browserjavascriptenabled": "true",
    "browserlanguage": "en",
    "browserscreenheight": "864",
    "browserscreenwidth": "1536",
    "browsertz": "120",
    "cachetoken": "eyJkYXRhY2VudGVydXJsIjogImh0dHBzOi8vd2Vic2VydmljZXMuc2VjdXJldHJhZGluZy5uZXQiLCAiY2FjaGV0b2tlbiI6ICI1Ny01ODRlOWMwNDliZTczZTIxNGNkZTU1MTk0NDQ3OWY4MGNhMzg3OGVmZTI1N2EzN2MwMWRmOTc1ZWRlYjI3YTBjIn0=",
    "challengewindowsize": "02",
    "currencyiso3a": "GBP",
    "customerip": "1.2.3.4",
    "expirydate": "01/2038",
    "pan": "4900490000000667",
    "paymenttypedescription": "DELTA",
    "requesttypedescription": "THREEDQUERY",
    "sitereference": "test_3dsapi12345",
    "termurl": "https://webhook.site/8543eb65-e5c7-40fc-a475-a862a825a562",
    "threedstransactionid": "cebcb773-3aa1-4bfa-a959-135aa50bb760",
    "threedscompind": "U",
    "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.93 Safari/537.36"
  }]
}

  THREEDQUERY Request Field Specification

Click here to open the field specification in a new tab.

 

THREEDQUERY Response Example

The following is an example of a THREEDQUERY response returned:

Raw JSON Raw XML 
{
  "requestreference": "W57-wr84pnjg",
  "response": [{
    "accounttypedescription": "ECOM",
    "acsreferencenumber": "ACS_REF",
    "acstransid": "c6a58c52-90a7-43d4-8beb-dfc5a42aeacc",
    "acsurl": "https://acs-mock.3ds.trustpayments.com/3ds/mock/acs/creq",
    "debtrepayment": "0",
    "enrolled": "Y",
    "errorcode": "0",
    "errormessage": "Ok",
    "issuer": "SecureTrading Test Issuer1",
    "issuercountryiso2a": "OM",
    "livestatus": "0",
    "maskedpan": "490049######0667",
    "merchantcategorycode": "0000",
    "merchantcountryiso2a": "GB",
    "merchantname": "Test Merchant 3DS",
    "merchantnumber": "9990000001",
    "operatorname": "webservices@example.com",
    "paymenttypedescription": "DELTA",
    "requesttypedescription": "THREEDQUERY",
    "settleduedate": "2022-06-14",
    "settlestatus": "0",
    "status": "C",
    "threedpayload": "eyJtZXNzYWdlVHlwZSI6ICJDUmVxIiwgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjogImNlYmNiNzczLTNhYTEtNGJmYS1hOTU5LTEzNWFhNTBiYjc2MCIsICJtZXNzYWdlVmVyc2lvbiI6ICIyLjIuMCIsICJhY3NUcmFuc0lEIjogImM2YTU4YzUyLTkwYTctNDNkNC04YmViLWRmYzVhNDJhZWFjYyIsICJjaGFsbGVuZ2VXaW5kb3dTaXplIjogIjAyIn0",
    "threedsservertransid": "cebcb773-3aa1-4bfa-a959-135aa50bb760",
    "threedversion": "2.2.0",
    "transactionreference": "57-100-36",
    "transactionstartedtimestamp": "2022-06-14 15:34:58"
  }],
  "secrand": "X",
  "version": "1.00"
}

  THREEDQUERY Response Field Specification

Click here to open the field specification in a new tab.

 

             

 

Step 4. Challenge

  Only perform this step if acsurl is returned in THREEDQUERY response.

To perform step-up authentication, you will need to create a form with action set to acsurl value, which was returned in the THREEDQUERY response. This form will need contain:

  • creq - This is the value of the threedpayload returned in THREEDQUERY response.
  • threeDSSessionData - This is a unique identifier to allow you to track the customer's session through the authentication process. The threedstransactionid value returned in the THREEDLOOKUP Response can be used for this purpose, or the requester can assign their own unique identifier. Where a requester assigns their own unique identifier, we would recommend using a GUID/UUID format.

Here is an example of such a form:

<html>
  <head>
    <meta charset="utf-8">
    <title>Trust Payments - 3D Secure Payment form</title>
  </head>
  <body onload="document.getElementById('3dform').submit();">
    <form method="POST" action="ACSURL" id="3dform">
      <input type="hidden" name="threeDSSessionData" value="threedsservertransid_VALUE" />
      <input type="hidden" name="creq" value="threedpayload_VALUE" />
      <noscript>
        <br>
        <br>
        <div style="text-align: center">
          <h1>Processing your 3D Secure Transaction</h1>
          <p>Please click continue to continue the processing of your 3D Secure transaction.</p>
          <input type="submit" class="button" value="continue"/>
        </div>
      </noscript>
    </form>
  </body>
</html>

Once the form is submitted, the customer would then be redirected to a page hosted by the ACS, where they would be expected to perform step-up authentication, typically by providing a previously agreed PIN and/or password or through biometric authentication, such as fingerprint or facial recognition.

Following this, the customer's browser is redirected to the termurl defined in step 3 (3-D Query). This redirect will include:

  • threeDSSessionData - You will need to check this matches the unique value included in the form to the ACS, as described above.
  • cres - The value returned should not be treated as the final authentication result. You should log the value of this field alongside the threeDSSessionData. You will receive the final authentication response as part of step 5 (3-D Result).

 

             

 

Step 5. THREEDRESULT

You must only verify the THREEDRESULT once the following conditions have been met:

  • The customer's browser has returned from the ACS-hosted page to the termurl defined in step 3 (3-D Query).
  • You've confirmed the threeDSSessionData that was sent to the termurl matches the unique value included in the form to the ACS.

 

THREEDRESULT Request Example

The following is an example of a THREEDRESULT request submitted using the Webservices API:

  For each 3-D Secure authentication session, your server should be configured to keep track of the session using the threedstransactionid field and ensure that only a single THREEDRESULT request is sent per unique threedstransactionid.

Raw JSON Raw XML 
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "parenttransactionreference": "57-100-36",
    "requesttypedescription": "THREEDRESULT",
    "sitereference": "test_3dsapi12345"
  }]
}

  THREEDRESULT Request Field Specification

Click here to open the field specification in a new tab.

 

THREEDRESULT Response Example

The following is an example of a THREEDRESULT response returned:

Raw JSON Raw XML 
{
  "requestreference": "W57-0epgmcxq",
  "response": [{
    "accounttypedescription": "ECOM",
    "baseamount": "1050",
    "cavv": "dHJ1c3RwYXltZW50c2F1dGhlbnQ=",
    "currencyiso3a": "GBP",
    "debtrepayment": "0",
    "eci": "05",
    "enrolled": "Y",
    "errorcode": "0",
    "errormessage": "Ok",
    "issuer": "SecureTrading Test Issuer1",
    "issuercountryiso2a": "OM",
    "livestatus": "0",
    "maskedpan": "490049######0667",
    "merchantcategorycode": "0000",
    "merchantcountryiso2a": "GB",
    "merchantname": "Test Merchant 3DS",
    "merchantnumber": "9990000001",
    "operatorname": "webservices@example.com",
    "parenttransactionreference": "57-100-36",
    "paymenttypedescription": "DELTA",
    "requesttypedescription": "THREEDRESULT",
    "settleduedate": "2022-06-14",
    "status": "Y",
    "threedacstransactionreference": "c6a58c52-90a7-43d4-8beb-dfc5a42aeacc",
    "threeddirectorytransactionreference": "65f1188b-4961-4590-a3e7-f350c22c1d45",
    "threedversion": "2.2.0",
    "transactionreference": "57-100-37",
    "transactionstartedtimestamp": "2022-06-14 15:36:33"
  }],
  "secrand": "D6sWTorcfyDv",
  "version": "1.00"
}

  THREEDRESULT Response Field Specification

Click here to open the field specification in a new tab.

 

             

 

Step 6. AUTH

Once the 3-D Secure process has completed, it is now time to process a transaction. Should you wish to proceed with the payment using the TRU Connect gateway, your server submits an AUTH request using Webservices API, including additional fields that you have received in the THREEDRESULT response.

 

AUTH Request Example

The following is an example of an AUTH request submitted using the Webservices API:

Raw JSON Raw XML 
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "accounttypedescription":"ECOM",
    "pan":"4900490000000667",
    "expirydate":"01/2038",
    "currencyiso3a":"GBP",
    "requesttypedescriptions":["AUTH"],
    "sitereference":"test_auth12347",
    "baseamount":"1050",
    "orderreference":"V2.2-TESTCASE9-VISA",
    "securitycode":"123",
    "cavv":"dHJ1c3RwYXltZW50c2F1dGhlbnQ=",
    "eci":"05",
    "xid":"",
    "enrolled":"Y",
    "status":"Y",
    "threedversion":"2.2.0",
    "threeddirectorytransactionreference":"65f1188b-4961-4590-a3e7-f350c22c1d45"
  }]
}

  AUTH Request Field Specification

Click here to open the field specification in a new tab.

 

AUTH Response Example

The following is an example of a AUTH response returned:

Raw JSON Raw XML 
{
  "requestreference": "W60-jfweuhp1",
  "response": [{
    "accounttypedescription": "ECOM",
    "acquirerresponsecode": "00",
    "authcode": "TEST54",
    "authmethod": "PRE",
    "baseamount": "1050",
    "cavv": "dHJ1c3RwYXltZW50c2F1dGhlbnQ=",
    "currencyiso3a": "GBP",
    "dccenabled": "0",
    "debtrepayment": "0",
    "eci": "05",
    "enrolled": "Y",
    "errorcode": "0",
    "errormessage": "Ok",
    "issuer": "SecureTrading Test Issuer1",
    "issuercountryiso2a": "OM",
    "livestatus": "0",
    "maskedpan": "490049######0667",
    "merchantcountryiso2a": "GB",
    "merchantname": "Test Merchant",
    "merchantnumber": "00000000",
    "operatorname": "webservices@example.com",
    "orderreference": "V2.2-TESTCASE9-VISA",
    "paymenttypedescription": "DELTA",
    "requesttypedescription": "AUTH",
    "securityresponseaddress": "0",
    "securityresponsepostcode": "0",
    "securityresponsesecuritycode": "2",
    "settleduedate": "2022-06-14",
    "settlestatus": "0",
    "splitfinalnumber": "1",
    "status": "Y",
    "threedversion": "2.2.0",
    "tid": "27880001",
    "transactionreference": "60-9-2473248",
    "transactionstartedtimestamp": "2022-06-14 15:37:35"
  }],
  "secrand": "HWCwdnmokhOsQV",
  "version": "1.00"
}

  AUTH Response Field Specification

Click here to open the field specification in a new tab.

 

Example 2 - Challenge- With threedmethodurl

 

Step 1. THREEDLOOKUP

THREEDLOOKUP Request Example

The following is an example of a THREEDLOOKUP request submitted using the Webservices API:

Raw JSON Raw XML 
{
  "alias": "webservices@example.com",
  "version": "1.00",
  "request": [{
    "accounttypedescription": "ECOM",
    "baseamount": "1050",
    "currencyiso3a": "GBP",
    "expirydate": "01/2038",
    "pan": "4900490000000550",
    "requesttypedescription": "THREEDLOOKUP",
    "sitereference": "test_3dsapi12345"
  }]
}

  THREEDLOOKUP Request Field Specification

Click here to open the field specification in a new tab.

 

THREEDLOOKUP Response Example

The following is an example of a THREEDLOOKUP response returned:

Raw JSON Raw XML 
{
  "requestreference": "W59-jpat4b7k",
  "response": [{
    "cachetoken": "eyJkYXRhY2VudGVydXJsIjogImh0dHBzOi8vd2Vic2VydmljZXMuc2VjdXJldHJhZGluZy5uZXQiLCAiY2FjaGV0b2tlbiI6ICI1OS1jMDQ1ZDYzN2FiYmQxN2JjZTVhYmFiMGJhZWFiYzBmODY0NGU1ZGIyOGY5YjYwZDMwNTNmZGMwNDE0NjllMDFiIn0=",
    "debtrepayment": "0",
    "errorcode": "0",
    "errormessage": "Ok",
    "maskedpan": "490049######0550",
    "paymenttypedescription": "DELTA",
    "requesttypedescription": "THREEDLOOKUP",
    "threedmethodurl": "https://acs-mock.3ds.trustpayments.com/3ds/mock/acs/method",
    "threednotificationurl": "https://brw.3ds.sandbox.trustpayments.com/3dss/brw/notification/threeDSMethod/332cf48e-0ef2-44f6-9c6b-b1bdc3797310/bcdd8e60-e16f-4dbc-a504-5156f011dc35",
    "threedstransactionid": "332cf48e-0ef2-44f6-9c6b-b1bdc3797310",
    "threedversion": "2.2.0",
    "transactionstartedtimestamp": "2022-06-15 12:08:50"
  }],
  "secrand": "hWOrHYh0r6tL",
  "version": "1.00"
}

  THREEDLOOKUP Response Field Specification

Click here to open the field specification in a new tab.

 

             

 

Step 2. Method URL

  Only perform this step if threedmethodurl is returned in the THREEDLOOKUP response.

Your system submits an HTTPS POST to the ACS using the base64-encoded threedmethodurl, including the threedstransactionid and threednotificationurl (returned in step 1). This is because when posting to the ACS, it is at this point they can capture information from the headers (e.g. the browser type). Later, the ACS returns a POST back to the threeDSMethodNotificationURL you included in the initial POST to the ACS.

 

For example:

{
  "threeDSServerTransID":"332cf48e-0ef2-44f6-9c6b-b1bdc3797310",
  "threeDSMethodNotificationURL":"https://webhook.site/8543eb65-e5c7-40fc-a475-a862a825a562"
}

  The default threednotificationurl value returned in the THREEDLOOKUP must be overridden with your own endpoint URL. This is used to receive an HTTPS POST from the ACS confirming the completion of the Method URL step.

 

This is then base64-encoded, resulting in:

eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjMzMmNmNDhlLTBlZjItNDRmNi05YzZiLWIxYmRjMzc5NzMxMCIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL3dlYmhvb2suc2l0ZS84NTQzZWI2NS1lNWM3LTQwZmMtYTQ3NS1hODYyYTgyNWE1NjIifQ==

 

  Ensure "==" characters are omitted when constructing the POST.

The following is an example of an HTTPS POST to the ACS that includes the threedmethodurl:

<form name="frm" method="POST" action="threedmethodurl">
<input type="hidden" name="threeDSMethodData"
value="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjMzMmNmNDhlLTBlZjItNDRmNi05YzZiLWIxYmRjMzc5NzMxMCIsInRocmVlRFNNZXRob2ROb3RpZmljYXRpb25VUkwiOiJodHRwczovL3dlYmhvb2suc2l0ZS84NTQzZWI2NS1lNWM3LTQwZmMtYTQ3NS1hODYyYTgyNWE1NjIifQ">
</form>

 

Method URL Request Field Specification

Required Field Format Length Description
X1-EN.png threeDSMethodNotificationURL URL

Not defined

The endpoint URL that will receive the notification of 3DS Method completion from the ACS.

Note: You must override the value of the threednotificationurl returned in the THREEDLOOKUP response.

This is sent in the initial request to the ACS from the 3DS Requestor executing the 3DS Method.
X1-EN.png threeDSServerTransID Alphanumeric including hyphens

36

Universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

The threeDSServerTransID submitted is taken from the value returned in the threedstransactionid field in the THREEDLOOKUP response.

 

Receive HTTPS POST from ACS to threeDSMethodNotificationURL

The threeDSMethodNotificationURL will receive the threeDSMethodData parameter, a base64-encoded JSON string that contains the threeDSServerTransID.

"threeDSMethodData"="eyJ0aHJlZURTU2VydmVyVHJhbnNJRCI6IjNhYzdjYWE3LWFhNDItMjY2My03OTFiLTJhYzA1YTU0MmM0YSJ9"
Decoded threeDSMethodData:
{"threeDSServerTransID":"332cf48e-0ef2-44f6-9c6b-b1bdc3797310"}

It may take up to 10 seconds for the ACS to send the HTTPS POST to your threeDSMethodNotificationURL.

  • If you receive this from the ACS within 10 seconds, proceed to step 3 (3-D Query) and set threedscompind to "Y" in the THREEDQUERY request.
  • If you do not receive this from the ACS within 10 seconds, proceed to step 3 (3-D Query) and set threedscompind to "N" in the THREEDQUERY request. (It is possible that you may still receive the message after 10 seconds has passed, but this can be ignored).

  The value of the base64-encoded threeDSMethodData must be stripped of = characters.

 

Method URL Response Field Specification

Required Field Format Length Description
X4-EN.png

threeDSMethodData

 Base64-encoded JSON string

N/A

 This contains the threeDSServerTransID, which is a universally unique transaction identifier assigned by the 3DS Server to identify a single transaction.

 

             

 

Step 3. THREEDQUERY

  It may not be possible to capture the customerip and accept (HTTP accept-header) from within the browser itself, therefore you'll need to configure an endpoint on your server, which will allow you to perform a GET request to return the customerip and accept values back to browser.

 

THREEDQUERY Request Example

The following is an example of a THREEDQUERY request submitted using the Webservices API:

Raw JSON Raw XML 
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "accept": "text/html,*/*",
    "accounttypedescription": "ECOM",
    "acquirerbin": "111111",
    "baseamount": "1050",
    "browsercolordepth": "24",
    "browserjavaenabled": "false",
    "browserjavascriptenabled": "true",
    "browserlanguage": "en",
    "browserscreenheight": "864",
    "browserscreenwidth": "1536",
    "browsertz": "120",
    "cachetoken": "eyJkYXRhY2VudGVydXJsIjogImh0dHBzOi8vd2Vic2VydmljZXMuc2VjdXJldHJhZGluZy5uZXQiLCAiY2FjaGV0b2tlbiI6ICI1OS1jMDQ1ZDYzN2FiYmQxN2JjZTVhYmFiMGJhZWFiYzBmODY0NGU1ZGIyOGY5YjYwZDMwNTNmZGMwNDE0NjllMDFiIn0=",
    "challengewindowsize": "02",
    "currencyiso3a": "GBP",
    "customerip": "1.2.3.4",
    "expirydate": "01/2038",
    "pan": "4900490000000550",
    "requesttypedescription": "THREEDQUERY",
    "sitereference": "test_3dsapi12345",
    "termurl": "https://webhook.site/8543eb65-e5c7-40fc-a475-a862a825a562",
    "threedstransactionid": "332cf48e-0ef2-44f6-9c6b-b1bdc3797310",
    "threedscompind": "Y",
    "useragent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/90.0.4430.93 Safari/537.36"
  }]
}

  THREEDQUERY Request Field Specification

Click here to open the field specification in a new tab.

 

THREEDQUERY Response Example

The following is an example of a THREEDQUERY response returned:

Raw JSON Raw XML 
{
  "requestreference": "W56-28nv861m",
  "response": [{
    "accounttypedescription": "ECOM",
    "acsreferencenumber": "ACS_REF",
    "acstransid": "2d99ebb4-5d47-4e62-9d94-7cfbb2fa5f93",
    "acsurl": "https://acs-mock.3ds.trustpayments.com/3ds/mock/acs/creq",
    "debtrepayment": "0",
    "enrolled": "Y",
    "errorcode": "0",
    "errormessage": "Ok",
    "issuer": "SecureTrading Test Issuer1",
    "issuercountryiso2a": "OM",
    "livestatus": "0",
    "maskedpan": "490049######0550",
    "merchantcategorycode": "0000",
    "merchantcountryiso2a": "GB",
    "merchantname": "Test Merchant 3DS",
    "merchantnumber": "9990000001",
    "operatorname": "webservices@example.com",
    "paymenttypedescription": "DELTA",
    "requesttypedescription": "THREEDQUERY",
    "settleduedate": "2022-06-15",
    "settlestatus": "0",
    "status": "C",
    "threedpayload": "eyJtZXNzYWdlVHlwZSI6ICJDUmVxIiwgInRocmVlRFNTZXJ2ZXJUcmFuc0lEIjogIjMzMmNmNDhlLTBlZjItNDRmNi05YzZiLWIxYmRjMzc5NzMxMCIsICJtZXNzYWdlVmVyc2lvbiI6ICIyLjIuMCIsICJhY3NUcmFuc0lEIjogIjJkOTllYmI0LTVkNDctNGU2Mi05ZDk0LTdjZmJiMmZhNWY5MyIsICJjaGFsbGVuZ2VXaW5kb3dTaXplIjogIjAyIn0",
    "threedsservertransid": "332cf48e-0ef2-44f6-9c6b-b1bdc3797310",
    "threedversion": "2.2.0",
    "transactionreference": "56-100-37",
    "transactionstartedtimestamp": "2022-06-15 12:12:09"
  }],
  "secrand": "Dv",
  "version": "1.00"
}

  THREEDQUERY Response Field Specification

Click here to open the field specification in a new tab.

 

             

 

Step 4. Challenge

  Only perform this step if acsurl is returned in THREEDQUERY response.

To perform step-up authentication, you will need to create a form with action set to acsurl value, which was returned in the THREEDQUERY response. This form will need contain:

  • creq - This is the value of the threedpayload returned in THREEDQUERY response.
  • threeDSSessionData - This is a unique identifier to allow you to track the customer's session through the authentication process. The threedstransactionid value returned in the THREEDLOOKUP Response can be used for this purpose, or the requester can assign their own unique identifier. Where a requester assigns their own unique identifier, we would recommend using a GUID/UUID format.

Here is an example of such a form:

<html>
  <head>
    <meta charset="utf-8">
    <title>Trust Payments - 3D Secure Payment form</title>
  </head>
  <body onload="document.getElementById('3dform').submit();">
    <form method="POST" action="ACSURL" id="3dform">
      <input type="hidden" name="threeDSSessionData" value="threedsservertransid_VALUE" />
      <input type="hidden" name="creq" value="threedpayload_VALUE" />
      <noscript>
        <br>
        <br>
        <div style="text-align: center">
          <h1>Processing your 3D Secure Transaction</h1>
          <p>Please click continue to continue the processing of your 3D Secure transaction.</p>
          <input type="submit" class="button" value="continue"/>
        </div>
      </noscript>
    </form>
  </body>
</html>

Once the form is submitted, the customer would then be redirected to a page hosted by the ACS, where they would be expected to perform step-up authentication, typically by providing a previously agreed PIN and/or password or through biometric authentication, such as fingerprint or facial recognition.

Following this, the customer's browser is redirected to the termurl defined in step 3 (3-D Query). This redirect will include:

  • threeDSSessionData - You will need to check this matches the unique value included in the form to the ACS, as described above.
  • cres - The value returned should not be treated as the final authentication result. You should log the value of this field alongside the threeDSSessionData. You will receive the final authentication response as part of step 5 (3-D Result).

 

             

 

Step 5. THREEDRESULT

You must only verify the THREEDRESULT once the following conditions have been met:

  • The customer's browser has returned from the ACS-hosted page to the termurl defined in step 3 (3-D Query).
  • You've confirmed the threeDSSessionData that was sent to the termurl matches the unique value included in the form to the ACS.

 

THREEDRESULT Request Example

The following is an example of a THREEDRESULT request submitted using the Webservices API:

  For each 3-D Secure authentication session, your server should be configured to keep track of the session using the threedstransactionid field and ensure that only a single THREEDRESULT request is sent per unique threedstransactionid.

Raw JSON Raw XML 
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "parenttransactionreference": "56-100-37",
    "requesttypedescription": "THREEDRESULT",
    "sitereference": "test_3dsapi12345"
  }]
}

  THREEDRESULT Request Field Specification

Click here to open the field specification in a new tab.

 

THREEDRESULT Response Example

The following is an example of a THREEDRESULT response returned:

Raw JSON Raw XML 
{
  "requestreference": "W59-3qutnaxv",
  "response": [{
    "accounttypedescription": "ECOM",
    "baseamount": "1050",
    "cavv": "dHJ1c3RwYXltZW50c2F1dGhlbnQ=",
    "currencyiso3a": "GBP",
    "debtrepayment": "0",
    "eci": "05",
    "enrolled": "Y",
    "errorcode": "0",
    "errormessage": "Ok",
    "issuer": "SecureTrading Test Issuer1",
    "issuercountryiso2a": "OM",
    "livestatus": "0",
    "maskedpan": "490049######0550",
    "merchantcategorycode": "0000",
    "merchantcountryiso2a": "GB",
    "merchantname": "Test Merchant 3DS",
    "merchantnumber": "9990000001",
    "operatorname": "webservices@example.com",
    "parenttransactionreference": "56-100-37",
    "paymenttypedescription": "DELTA",
    "requesttypedescription": "THREEDRESULT",
    "settleduedate": "2022-06-15",
    "status": "Y",
    "threedacstransactionreference": "2d99ebb4-5d47-4e62-9d94-7cfbb2fa5f93",
    "threeddirectorytransactionreference": "be064933-c5bd-4f76-8198-cfd99b6bedf0",
    "threedversion": "2.2.0",
    "transactionreference": "59-100-37",
    "transactionstartedtimestamp": "2022-06-15 12:15:03"
  }],
  "secrand": "gh33Hh3JJD0",
  "version": "1.00"
}

  THREEDRESULT Response Field Specification

Click here to open the field specification in a new tab.

 

             

 

Step 6. AUTH

Once the 3-D Secure process has completed, it is now time to process a transaction. Should you wish to proceed with the payment using the TRU Connect gateway, your server submits an AUTH request using Webservices API, including additional fields that you have received in the THREEDRESULT response.

 

AUTH Request Example

The following is an example of an AUTH request submitted using the Webservices API:

Raw JSON Raw XML 
{
  "alias":"webservices@example.com",
  "version":"1.00",
  "request":[{
    "accounttypedescription":"ECOM",
    "pan":"4900490000000550",
    "expirydate":"01/2038",
    "currencyiso3a":"GBP",
    "requesttypedescriptions":["AUTH"],
    "sitereference":"test_auth12347",
    "baseamount":"1050",
    "orderreference":"V2.2-TESTCASE13-VISA",
    "securitycode":"123",
    "cavv":"dHJ1c3RwYXltZW50c2F1dGhlbnQ=",
    "eci":"05",
    "xid":"",
    "enrolled":"Y",
    "status":"Y",
    "threedversion":"2.2.0",
    "threeddirectorytransactionreference":"65f1188b-4961-4590-a3e7-f350c22c1d45"
  }]
}

  AUTH Request Field Specification

Click here to open the field specification in a new tab.

 

AUTH Response Example

The following is an example of a AUTH response returned:

Raw JSON Raw XML 
{
  "requestreference": "W59-0av0n4ku",
  "response": [{
    "accounttypedescription": "ECOM",
    "acquirerresponsecode": "00",
    "authcode": "TEST30",
    "authmethod": "PRE",
    "baseamount": "1050",
    "cavv": "dHJ1c3RwYXltZW50c2F1dGhlbnQ=",
    "currencyiso3a": "GBP",
    "dccenabled": "0",
    "debtrepayment": "0",
    "eci": "05",
    "enrolled": "Y",
    "errorcode": "0",
    "errormessage": "Ok",
    "issuer": "SecureTrading Test Issuer1",
    "issuercountryiso2a": "OM",
    "livestatus": "0",
    "maskedpan": "490049######0550",
    "merchantcountryiso2a": "GB",
    "merchantname": "Test Merchant",
    "merchantnumber": "00000000",
    "operatorname": "webservices@example.com",
    "orderreference": "V2.2-TESTCASE13-VISA",
    "paymenttypedescription": "DELTA",
    "requesttypedescription": "AUTH",
    "securityresponseaddress": "0",
    "securityresponsepostcode": "0",
    "securityresponsesecuritycode": "2",
    "settleduedate": "2022-06-15",
    "settlestatus": "0",
    "splitfinalnumber": "1",
    "status": "Y",
    "threedversion": "2.2.0",
    "tid": "27880001",
    "transactionreference": "59-9-2486253",
    "transactionstartedtimestamp": "2022-06-15 12:15:49"
  }],
  "secrand": "j7ZmqibsHXGjR",
  "version": "1.00"
}

  AUTH Response Field Specification

Click here to open the field specification in a new tab.

 

    Back:  Frictionless Flow Walkthrough  Next:   Testing Resources    

Was this article helpful?
0 out of 0 found this helpful
Avatar
Michael Buckley

 

Further reading on this topic