Handling 3DS API responses

  Last updated: 

 

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:

Raw JSON Raw XML
{
"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"
}

 

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:

Error code 22000 - Bypass

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.

Raw JSON Raw XML
{
"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"
}
Error code 60031 - Invalid acquirer for 3-D Secure

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.

Raw JSON Raw XML
{
"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"
}

 

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    

Was this article helpful?
0 out of 0 found this helpful
Have more questions? Submit a request