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:
Errorcode 22000 is returned when the paymenttypedescription is not supported for 3-D Secure. When this error is returned, you can proceed to payment, although please be aware that there will be no liability shift in this scenario.
{
"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>
Errorcode 60031 is returned when the customer's bank is not supported for 3-D Secure. When this error is returned, you can proceed to payment, although please be aware that there will be no liability shift in this scenario.
{
"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
