Common Error Scenarios

The page lists common error scenarios you might encounter during the 3DS testing and integration process. This list is not comprehensive of all errors that you might encounter, but shows examples of sample requests and responses that you can use to understand an error and resolve the problem.

error_outline
note

Some error scenarios have the same error code; therefore, it is important that you also check other parameters in the error request and response.

Legend for errorComponent parameter in the sample responses:

  • C = FSG SDK
  • S = 3DS Server (Elavon)
  • D = DS (Directory Server)
  • A = ACS (Access Control Server of the Issuer)

Error scenario: Unsupported account/card number

Sample request

POST https://uat.gw.fraud.eu.elavonaws.com/3ds2/lookup

{
   "messageId" : "TEST-Message_ID",
   "acctNumber" : "4761739001010036",
   "doBinLookup" : false
}

Sample response

{
   "messageId" : "TEST-Message_ID",
   "error" : {
      "messageType" : "Erro",
      "messageVersion" : "2.1.0",
      "threeDSServerTransID" : "4d23342e-c3bd-4819-b599-790872b1e14a",
      "errorCode" : "305",
      "errorComponent" : "S",
      "errorDescription" : "Account number not supported",
      "errorDetail" : "Account number not supported by 3DS 2.1. Validate the account number: 47XXXXXXXXXX0036",
      "errorMessageType": "AReq"
   }
}

Proposed solution

Validate the account number is correct or try a different account number that is supported by EMV 3DS 2.1.

Error scenario: Invalid account number format

Sample request

POST https://uat.gw.fraud.eu.elavonaws.com/3ds2/lookup

{
   "messageId" : "Test",
   "acctNumber" : "77878",
   "doBinLookup" : false
}

Sample response

{
   "messageId" : "Test",
   "error" : {
      "messageType" : "Erro",
      "messageVersion" : "2.1.0",
      "threeDSServerTransID" : "b18a7e4d-9ac6-4674-b362-b40f95b73955",
      "errorCode" : "203",
      "errorComponent" : "S",
      "errorDescription" : "Data element not in the required format or value is invalid",
      "errorDetail" : "acctNumber[77878]: must be a valid account number, must be a valid value format. Refer to the documentation to see the sample request and the field parameters description to understand the correct field value format."
   }
}

Proposed solution

Validate the account number is correct or try a different account number that is supported by EMV 3DS 2.1.

Error scenario: Incorrect threeDSServerTransID

Sample request

GET https://uat.gw.fraud.eu.elavonaws.com/3ds2/challenge_result/9cc9864E-9f84-45d1-a828-95dac65d9cbd

Sample response

{
   "error" : {
      "messageType" : "Erro",
      "messageVersion" : "2.1.0",
      "threeDSServerTransID" : "9cc9864E-9f84-45d1-a828-95dac65d9cbd",
      "errorCode" : "301",
      "errorComponent" : "S",
      "errorDescription" : "Unknown Transaction ID",
      "errorDetail" : "Unknown Transaction ID. Validate the threeDSServerTransID in the request is the same as returned in the authentication response (/3ds2/authenticate) returned by the 3DS Server"
   }
}    

Proposed solution

Validate the threeDSServerTransID in the request has the same value as returned in the authentication response (/3ds2/authenticate) returned by the 3DS Server.

Error scenario: Malformed JSON request

Sample request

POST https://uat.gw.fraud.eu.elavonaws.com/3ds2/lookup

{
   "messageID" : "Test_ID",
   "acctNumber" : "370000000000002",rgbrbrbrbrb,
   "doBinLookup" : false
}

Sample response

{
   "error" : {
      "messageType" : "Erro",
      "messageVersion" : "2.1.0",
      "threeDSServerTransID" : "d13fd3d5-7352-4c07-9775-c781e32180de",
      "errorCode" : "101",
      "errorComponent" : "S",
      "errorDescription" : "Message not recognized",
      "errorDetail" : "The JSON request is in an incorrect format. Please validate the request. Refer to the documentation to see the sample request and the field parameters description to understand the correct field value format."
   }
}

Proposed solution

Validate the JSON request. See Sample lookup request

Error scenario: Invalid ISO code (currency or country)

error_outline
note

In this sample request, the billAddrCountry field value is incorrect. This request intentionally shows only some parameters of an authenticate request.

Sample request

POST https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticate

{
    "messageId": "TEST-Mesaage_ID"
    "aReq": {
        "acctID": "personal account",
        "acctInfo": {
            "chAccAgeInd": "03",
            "chAccChange": "20160712",
            ........................
      },
        "billAddrCity": "Bill City Name",
        "billAddrCountry": "999",
        .........................
}

Sample response

{
   "messageId" : "TEST-Message_ID",
   "error" : {
     "messageType" : "Erro",
     "messageVersion" : "2.1.0",
     "threeDSServerTransID" : "fb3b7f46-e3fa-48c7-9d68-1fbbe4f7d130",
     "errorCode" : "304",
     "errorComponent" : "S",
     "errorDescription" : "ISO code is not valid",
     "errorDetail" : "aReq.billAddrCountry[999]: must be a valid ISO 3166-1 three-digit country code. Refer to the documentation to see the sample request and the field parameters description to understand the correct field value format."
   }
}

Proposed solution

Validate the country code is a valid ISO 3166-1 numeric three-digit country code.

Error scenario: Invalid field value (Length, or format, or value is incorrect)

error_outline
note

In this sample request, the cardExpiryDate field value is incorrect. This request intentionally shows only some parameters of an authenticate request.

Sample request

POST https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticate

{
   "messageId": "TEST-Mesaage_ID",
   "aReq" : {
         "threeDSCompInd" : "Y",
         "addrMatch" : "N",
         "cardExpiryDate" : "0",
         "acctNumber" : "370000000000000",
         "billAddrCity" : "Bill City Name",
         "billAddrCountry" : "840",
         ...............
         ...............
         "broadInfo" : {
            "message" : "TLS 1.x will be turned off starting summer 2019"
         }
      }
}

Sample response

{
   "error" : {
      "messageType" : "Erro",
      "messageVersion" : "2.1.0",
      "threeDSServerTransID" : "ae419b78-513e-4f7b-ba3b-f2fba639ca2a",
      "sdkTransID" : "8a880dc0-d2d2-4067-bcb1-b08d1690b26e",
      "errorCode" : "203",
      "errorComponent" : "S",
      "errorDescription" : "Data element not in the required format or value is invalid",
      "errorDetail" : "aReq.cardExpiryDate[0]: must be a valid value format. Refer to the documentation to see the sample request and the field parameters description to understand the correct field value format."
   }
}

Proposed solution

Refer to the documentation to see the sample request and the field parameters description to understand the correct field value format.

Error scenario: One or more required or conditionally required fields are missing

error_outline
note

In this sample request, the threeDSRequestorAuthenticationInd field value is null. This request intentionally shows only some parameters of an authenticate request.

Sample request

POST https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticate

{
   "aReq" : {
      "threeDSCompInd" : "Y",
      "addrMatch" : "N",
      "cardExpiryDate" : "1912",
      "acctNumber" : "4017730000000005",
      .......................
      .......................
      "threeDSServerTransID" : "ea30f4f0-fc95-4014-aa7d-a0db31dc41bd",
      "threeDSRequestorAuthenticationInd" : null,
      "threeDSRequestorAuthenticationInfo" : {
         "threeDSReqAuthMethod" : "02",
         "threeDSReqAuthTimestamp" : "201711071307",
         "threeDSReqAuthData" : "cKTYtrvvKU7gUoiqbbO7Po"
      },
      ......................
      ......................
      "broadInfo" : {
         "message" : "TLS 1.x will be turned off starting summer 2019"
      }
   }
}

Sample response

{
   "error" : {
      "messageType" : "Erro",
      "messageVersion" : "2.1.0",
      "threeDSServerTransID" : "2b8dae62-1d7f-48c4-b456-1010a64486c5",
      "sdkTransID" : "8a880dc0-d2d2-4067-bcb1-b08d1690b26e",
      "errorCode" : "201",
      "errorComponent" : "S",
      "errorDescription" : "Required data element is missing",
      "errorDetail" : "aReq.threeDSRequestorAuthenticationInd[null]: Field 'threeDSRequestorAuthenticationInd' cannot be null based on condition: deviceChannel=BRW in [APP, BRW]"
   }
}

Proposed solution

If the value of a required or a conditionally required field is set to null or the field is missing in the request, the errorCode in the response is 201. Refer to the documentation to see the sample request and the field parameters description to understand if a field is required, conditionally required, or optional.

Error scenario: One or more fields are duplicate

error_outline
note

In this sample request, the threeDSCompInd field value is duplicate. This request intentionally shows only some parameters of an authenticate request.

Sample request

POST https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticate

{
   "aReq" : {
      "threeDSCompInd" : "Y",
      "threeDSCompInd" : "Y",
      "addrMatch" : "N",
      "cardExpiryDate" : "1910",
      "acctNumber" : "370000000000000",
      ...................
      ...................
      "broadInfo" : {
         "message" : "TLS 1.x will be turned off starting summer 2019"
      }
   }
}

Sample response

{
   "error" : {
   "messageType" : "Erro",
   "messageVersion" : "2.1.0",
   "threeDSServerTransID" : "d3e4d9f2-19f0-4ade-8482-cf3f3158d83f",
   "errorCode" : "204",
   "errorComponent" : "S",
   "errorDescription" : "Data element present more than once in the message",
   "errorDetail" : "Duplicate field 'threeDSCompInd'. Refer to the documentation to see the sample request and the field parameters description to understand the correct field value format."
   }
}

Proposed solution

Validate the request to check for any duplicate parameters.

One or more optional or conditionally optional fields are empty or null

error_outline
note

In this sample request, the threeDSRequestorChallengeInd field, an optional field, value is null. This request intentionally shows only some parameters of an authenticate request.

Sample request

POST https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticate

{
   "aReq" : {
      "threeDSCompInd" : "Y",
      "addrMatch" : "N",
      "cardExpiryDate" : "1912",
      "acctNumber" : "4017730000000005",
      "billAddrCity" : "Bill City Name",
      "billAddrCountry" : "840",
      "transType" : "01",
      "threeDSServerTransID" : "b168994d-0b25-4232-8153-8ecc58f2ee85",
      "threeDSRequestorAuthenticationInd" : "01",
      "threeDSRequestorAuthenticationInfo" : {
      "threeDSReqAuthMethod" : "02",
      "threeDSReqAuthTimestamp" : "201711071307",
      "threeDSReqAuthData" : "cKTYtrvvKU7gUoiqbbO7Po",
   },
      "threeDSRequestorChallengeInd" : null,
      ...................
      ...................
      "broadInfo" : {
         "message" : "TLS 1.x will be turned off starting summer 2019"
      }
   }
}

Sample response

{
   "error" : {
   "messageType" : "Erro",
   "messageVersion" : "2.1.0",
   "threeDSServerTransID" : "48495f82-9ca1-46c4-8fde-bfd9c53e4236",
   "errorCode" : "203",
   "errorComponent" : "S",
   "errorDescription" : "Data element not in the required format or value is invalid",
   "errorDetail" : "JSON parse error: Invalid `null` value encountered for property \"threeDSRequestorChallengeInd\""
  }
}

Proposed solution

Validate the request to check if the value of any parameters is null. The error detail highlights the parameter whose value is set to null. Note that if there are two or more parameters whose value is set to null, the errorDetail lists only the first parameter whose value is set to null.

Request JSON body is empty

error_outline
note

In sample request 1 and 2, the JSON body is empty.

Sample request 1

POST https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticate

{
   "aReq" : {

   }
}

Sample response for sample request 1

{
   "error" : {
   "messageType" : "Erro",
   "messageVersion" : "2.1.0",
   "threeDSServerTransID" : "534d910c-8034-40fb-8d7c-edda240a827a",
   "errorCode" : "201",
   "errorComponent" : "S",
   "errorDescription" : "Missing required data element",
   "errorDetail" : "aReq.acctNumber: must be present; aReq.deviceChannel: must be present; aReq.messageCategory: must be present. Refer to the documentation to see the sample request and the field parameters description to understand the correct field value format."
  }
}

Sample request 2

POST https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticate

{  
}

Sample response for sample request 2

{
   "error" : {
   "messageType" : "Erro",
   "messageVersion" : "2.1.0",
   "threeDSServerTransID" : "534d910c-8034-40fb-8d7c-edda240a827a",
   "errorCode" : "201",
   "errorComponent" : "S",
   "errorDescription" : "Missing required data element",
   "errorDetail" : "aReq: must be present. Refer to the documentation to see the sample request and the field parameters description to understand the correct field value format."
  }
}

Sample request 3

POST https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticate

error_outline
note

In sample request 3, the JSON request is empty.

Sample response for sample request 3

{
   "error" : {
   "messageType" : "Erro",
   "messageVersion" : "2.1.0",
   "threeDSServerTransID" : "534d910c-8034-40fb-8d7c-edda240a827a",
   "errorCode" : "101",
   "errorComponent" : "S",
   "errorDescription" : "Message not recognised",
   "errorDetail" : "The JSON request is in an incorrect format. Please validate the request. Refer to the documentation to see the sample request and the field parameters description to understand the correct field value format."
  }
}

Proposed solution

Note that the HTTP response code is HTTP/1.1 200 OK, but the error code 101 or 201 is also present. Validate the request body has all the required parameters.

See documentation for a list of required parameters for each request sent to the 3DS Server.

Fields related to merchant boarding is missing in the lookup request

Sample scenario

The 3DS Server auto populates fields related to a merchant (integrator) such as acquirerBIN, threeDSRequestorID, threeDSRequestorName, etc. in the /3ds2/lookup request from the data entered in the merchant boarding portal. However, if any of these fields are missing, the lookup response returns an error message.

If you send a /3ds2/authenticate request without sending the /3ds2/lookup request and the merchant boarding information is missing, the authenticate response also returns an error message.

Sample error response

If threeDSRequestorID is missing in the lookup request:

{
   "error" : {
   "messageType" : "Erro",
   "messageVersion" : "2.1.0",
   "threeDSServerTransID" : "534d910c-8034-40fb-8d7c-edda240a827a",
   "errorCode" : "305",
   "errorComponent" : "S",
   "errorDescription" : "Invalid transaction data",
   "errorDetail" : "Unexpected: Missing ThreeDSRequestorID for card scheme: <card scheme name>."
  }
}

If threeDSRequestorName is missing in the lookup request:

{
   "error" : {
   "messageType" : "Erro",
   "messageVersion" : "2.1.0",
   "threeDSServerTransID" : "534d910c-8034-40fb-8d7c-edda240a827a",
   "errorCode" : "305",
   "errorComponent" : "S",
   "errorDescription" : "Invalid transaction data",
   "errorDetail" : "Unexpected: Missing ThreeDSRequestorName for card scheme: <card scheme name>."
  }
}

If acquirerBIN is missing in the lookup request:

{
   "error" : {
   "messageType" : "Erro",
   "messageVersion" : "2.1.0",
   "threeDSServerTransID" : "534d910c-8034-40fb-8d7c-edda240a827a",
   "errorCode" : "305",
   "errorComponent" : "S",
   "errorDescription" : "Invalid transaction data",
   "errorDetail" : "Unexpected: Missing AcquirerBIN for country code <three-digit country code> and card scheme: <card scheme name>."
  }
}

Proposed solution

To resolve this issue, contact Elavon support.

messageExtenstion.criticalityIndicator set to true results in an error response

The EMV 3D Secure specifications do not have a clearly defined critical or non-critical extension for 3D Secure version 2.1. If the criticalityIndicator parameter in the messageExtension array is set to true in the authentication request, the 3DS Server returns an error response if the extension is not recognized.

error_outline
note

In this sample request, the criticalityIndicator field value is set to true. This request intentionally shows only some parameters of an authenticate request.

Sample request

POST https://uat.gw.fraud.eu.elavonaws.com/3ds2/authenticate

{
      "messageId" : "Testing 202",
      "aReq" : {
         "threeDSCompInd" : "Y",
         "addrMatch" : "N",
         "cardExpiryDate" : "0",
         "acctNumber" : "370000000000000",
         "billAddrCity" : "Bill City Name",
         "billAddrCountry" : "840",
          ...............
          ...............
         "messageExtension" : [
          {
            "name" : "msgextname",
            "id" : "501341592B_0001_4567",
            "criticalityIndicator" :  true,
            "data" : {
               "valueOne" : "messageextensiondata",
               "valueTwo" : "moremessageextensiondata"
             }
           }
         ],
        "broadInfo" : {
            "message" : "TLS 1.x will be turned off starting summer 2019"
        }
     }
}

Sample response

{
  "messageId" : "Testing 202",
  "error" : {
      "messageType" : "Erro",
      "messageVersion" : "2.1.0",
      "threeDSServerTransID" : "c7d7ed53-2829-43fc-bdf9-874733d86462",
      "errorCode" : "202",
      "errorComponent" : "S",
      "errorDescription" : "Critical message extension not recognised",
      "errorDetail" : "aReq.messageExtension[0][MessageExtension(name=msgextname, id=501341592B_0001_4567,criticalityIndicator=true, data={valueOne=messageextensiondata, valueTwo=moremessageextensiondata})]: Unrecognized critical extension. Refer to the documentation to see the sample request and the field parameters description to understand the correct field value format"
  }
}

Proposed solution

Set the criticalityIndicator field value to false.

Related topics