Handling 3DS API responses

When you receive a response following a request sent using our 3DS API, your system will need to perform the following checks on the values returned (where applicable) to ensure the request was processed successfully.

Response structure

Your system will be returned numerous fields in the response object. You will need to interpret the contents of these fields to ensure they are the values expected.

The following is an example of a THREEDLOOKUP response:

{
  "requestreference": "A3579dkvx",
  "response": [{
    "cachetoken": "XXXXX",
    "errorcode": "0",
    "errormessage": "Ok",
    "maskedpan": "490049######0501",
    "paymenttypedescription": "DELTA",
    "requesttypedescription": "THREEDLOOKUP",
    "threedstransactionid": "733ab129-1126-4b80-97a4-f3d8fee9c564",
    "threedversion": "2.2.0",
    "transactionstartedtimestamp": "2022-05-24 12:59:27"
  }],
  "secrand": "VqOIoVXOJP7rZuxw",
  "version": "1.00"
}

<responseblock version="3.67">
  <requestreference>A3579dkvx</requestreference>
  <response type="THREEDLOOKUP">
    <operation>
      <cachetoken>XXXXX</cachetoken>
    </operation>
    <billing>
      <payment type="DELTA">
        <pan>490049######0501</pan>
      </payment>
    </billing>
    <error>
      <message>Ok</message>
      <code>0</code>
    </error>
    <threedsecure>
      <transactionid>733ab129-1126-4b80-97a4-f3d8fee9c564</version>
    </threedsecure>
    <timestamp>2022-05-24 12:59:27</timestamp>
  </response>
  <secrand>VqOIoVXOJP7rZuxw</secrand>
</responseblock></responseblock>

Error code

The errorcode is a fundamentally important field as it displays the outcome of the submitted request. Your system must check the code returned and handle the situation according to the code returned. The following is a list of common errorcode values that can be returned that your system should expect and be able to handle:

{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "errorcode": "22000",
    "errormessage": "Bypass",
    "requesttypedescription": "ERROR",
    "transactionreference": "44-2-81001",
    "transactionstartedtimestamp": "2022-03-29 06:43:42"
  }],
  "secrand":"zO9"
}

<responseblock version="3.67">
  <requestreference>X617j6u8v</requestreference>
  <response type="ERROR">
    <error>
      <code>22000</code>
      <message>Bypass</message>
    </error>
    <timestamp>2022-03-29 06:43:42</timestamp>
    <transactionreference>44-2-81001</transactionreference>
  </response>
  <secrand>D2i8Z</secrand>
</responseblock>

{
  "requestreference":"W23-fjgvn3d8",
  "version":"1.00",
  "response":[{
    "accounttypedescription": "ECOM",
    "errorcode": "60031",
    "errormessage": "Invalid acquirer for 3-D Secure",
    "issuercountryiso2a": "US",
    "livestatus": "0",
    "maskedpan": "630485######0701",
    "merchantcountryiso2a": "GB",
    "merchantname": "Test Merchant",
    "merchantnumber": "00000000",
    "operatorname": "webservices@example.com",
    "paymenttypedescription": "LASER",
    "requesttypedescription": "THREEDQUERY",
    "tid": "27882788",
    "transactionreference": "44-2-81003",
    "transactionstartedtimestamp": "2022-03-28 19:57:15",
    "settleduedate": "2022-03-28",
    "settlestatus": "0"
  }],
  "secrand":"zO9"
}

<responseblock version="3.67">
  <requestreference>Xpbt194u6</requestreference>
  <response type="THREEDQUERY">
    <billing>
      <payment type="LASER">
        <issuercountry>US</issuercountry>
        <pan>630485######0701</pan>
      </payment>
    </billing>
    <error>
      <code>60031</code>
      <message>Invalid acquirer for 3-D Secure</message>
    </error>
    <live>0</live>
    <merchant>
      <merchantcountryiso2a>GB</merchantcountryiso2a>
      <merchantname>Test Merchant</merchantname>
      <merchantnumber>00000000</merchantnumber>
      <operatorname>webservices@example.com</operatorname>
      <tid>27882788</tid>
    </merchant>
    <operation>
      <accounttypedescription>ECOM</accounttypedescription>
    </operation>
    <settlement>
      <settleduedate>2022-03-28</settleduedate>
      <settlestatus>0</settlestatus>
    </settlement>
    <timestamp>2022-03-28 19:57:15</timestamp>
    <transactionreference>44-2-81003</transactionreference>
  </response>
  <secrand>bUQL</secrand>
</responseblock>

Enrolled

If the THREEDQUERY response includes enrolled with value "N", this means the card is not enrolled in a 3-D Secure scheme. Before proceeding with an authorisation request with an unenrolled card, you must first check the value of the issuercountryiso2a field returned to determine the country where the card was issued. If the issuer country is the UK or within the EEA, you must not continue with the transaction, in order to remain compliant with PSD2. However, if the issuer country is outside the UK and EEA, you can choose to proceed with the transaction with the understanding that there will be no liability shift.

Request type

Each response will contain a requesttypedescription. The value of this field returned in the response should always match the value submitted in the request.

If you receive requesttypedescription with value “ERROR”, the request may not have been processed successfully and you will need to investigate.

Live status

This value is returned in THREEDQUERY response messages:

• 0 - Test processing
• 1 - Live processing

    Back:   Getting started with 3DS API  Next:   Frictionless Flow Walkthrough