Common Error Scenarios

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

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.

Common error scenarios:

Legend for the errorComponent parameter in the sample responses:

  • C = Mobile 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. 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.

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. The acctNumber field value must be between 13-19 digits and must not have any space or special character between the digits.

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)

note

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

Sample request

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

{
   //This example request intentionally shows only some parameters of an authenticate request.
    "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)

note

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

Sample request

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

{
   //This example request intentionally shows only some parameters of an authenticate request.
   "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

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

{
   //This example request intentionally shows only some parameters of an authenticate request.
   "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 for 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

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

{
   //This example request intentionally shows only some parameters of an authenticate request.
   "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.

Error scenario: One or more optional or conditionally optional fields are empty or null

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

{
   //This example request intentionally shows only some parameters of an authenticate request.
   "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.

Error scenario: Request JSON body is empty

note

In sample requests 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

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.

Error scenario: 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.2.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.

Error scenario: 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.

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

{
   //This example request intentionally shows only some parameters of an authenticate request.
   "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.

Error scenario: Mandatory fields missing in the /authenticate request for a service provider merchant

The /3ds2/authenticate request for a service provider merchant (a merchant who does not process with Elavon)[is missing one or more of the following field values.

3DS 2.1/2.2 authentication

  • Acquirer Merchant Id (acquirerMerchantID)
  • Acquirer BIN (acquirerBIN)
  • 3DS Requestor ID (threeDSRequestorID)
  • 3DS Requestor Name (threeDSRequestorName)

Sample response for a 3DS 2.1/2.2 authentication

{
    "messageId": "mr-test",
    "error": {
        "messageType": "Erro",
        "messageVersion": "2.1.0",
        "threeDSServerTransID": "b34f63fd-40ec-42b8-9ba1-ec18a53c392d",
        "sdkTransID": "8a880dc0-d2d2-4067-bcb1-b08d1690b26e",
        "errorCode": "201",
        "errorComponent": "S",
        "errorDescription": "Missing required data element",
        "errorDetail": "acquirerBIN: must be present; acquirerMerchantID: must be present; threeDSRequestorID: must be present; threeDSRequestorName: must be present. Refer to the documentation to see the sample request and the field parameters description to understand the correct field value format",
        "errorMessageType": "AReq"
    }
}

Related topics