3DS 2.1 Deprecation Notice
EMVCo and the card schemes will shortly be sunsetting 3D Secure version 2.1.
Please contact Ravelin if you have any questions in advance of this change.

3DS Error Responses

If a problem occurs during 3DS processing an error response will be returned.

Error Response

The format of the 3DS error response is shown below. Depending on the error, not all fields will be present in the response.

Show all
status integer

The HTTP response status code.

Example: 400
timestamp integer

The Unix timestamp of when the response was generated.

Example: 1629395847
message string

A description of the error.

cardScheme string

The card scheme of the card for which 3DS was being performed.

Options:
Visa
Mastercard
Discover
American Express
JCB
Cartes Bancaires
UPI
errors array

An array of strings describing individual validation errors which were identified in the request.

See our 3D Secure API reference for validation conditions.

docs string

A link to the relevant section of our 3D Secure API reference for addressing the errors.

data object

The EMV 3DS Error message.

Hide definition
messageType string

The 3DS error message type. Will always be the four character, 3DS message type "Erro".

Example: "Erro"
messageVersion string

The 3DS error message protocol version.

Note, this is the version of the error message, which may not be the same as the version used by the 3DS transaction.

Example: "2.2.0"
threeDSServerTransID string

The unique 3DS Server identifier for the 3DS transaction which encountered the error.

dsTransID string

The unique Directory Server identifier for the 3DS transaction which encountered the error.

acsTransID string

The unique ACS identifier for the 3DS transaction which encountered the error.

sdkTransID string

The unique 3DS SDK identifier for the 3DS transaction which encountered the error.

errorComponent string

The 3DS component which identified the error. Note, this is not the component where the error originated.

If the value is "S" the Ravelin 3DS Server identified an error in the directory server response. The directory server will have been notified.

If the value is "D" or "A" the directory server or ACS identified an error and Ravelin have been notified. See the errorDescription and errorDetail for more information.

Options:
S

3DS Server

D

Directory Server (DS)

A

Access Control Server (ACS)

C

3DS SDK

errorDescription string

A description of the problem which caused the error.

errorDetail string

Additional detail regarding the problem which caused the error.

errorCode string

The 3DS Error code. This can be used to group 3DS errors into certain categories.

Check the errorDescription and errorDetail fields for more information.

Note, this is not the HTTP status code.

Options:
101

Invalid message

102

3DS message version not supported

201

A required field is missing

202

Critical message extensions not recognised

203

The format of one or more of the fields is invalid

204

One or more fields is duplicated

301

A transaction ID was invalid (threeDSServerTransID, dsTransID, acsTransID or sdkTransID)

302

Data decryption failure

303

Access denied

304

ISO country or currency code was invalid

305

Transaction data was invalid

306

Merchant Category Code (MCC) was invalid for the payment system

402

Transaction timed out

403

Transient system failure

404

Permanent system failure

405

System connection failure

errorMessageType string

The 3DS message type which was identified as containing an error.

Options:
AReq
ARes
CReq
CRes

Example Errors

Invalid API Key
HTTP Status 401
Ensure you are using the correct Secret API Key. See Authentication.

{
    "status": 401,
    "timestamp": 1629395847,
    "message": "Unable to verify authentication"
}

HTTP Method is invalid
HTTP Status 405
Ensure you have used the correct HTTP Method (POST, GET) for the request.

{
    "status": 405,
    "timestamp": 1636729123,
    "message": "Method Not Allowed - HTTP method must be POST"
}

Incorrect Content-Type Header
HTTP Status 415
For POST requests the Content-Type header must be application/json; charset=UTF-8.

{
    "status": 415,
    "timestamp": 1636729260,
    "message": "Unsupported Media Type - 'Content-Type' header must be 'application/json; charset=utf-8'"
}

Invalid PAN
HTTP Status 400
The primary account number (PAN) must be numeric, between a length of 13 and 19 digits.

{
    "status": 400,
    "timestamp": 1636733016,
    "message": "Bad Request - pan must be numeric, between a length of 13 and 19 digits"
}

Card is not supported by any of the card schemes for 3DS2
HTTP Status 400

{
  "status": 400,
  "timestamp": 1658926425,
  "message": "Validation error",
  "data": {
    "threeDSServerTransID": "2407c5db-2a35-4dc1-bc5f-8d8fb878ef87",
    "errorCode": "305",
    "errorComponent": "S",
    "errorDescription": "Cardholder Account Number is not in a range belonging to Issuer.",
    "errorDetail": "The card was not supported by any card schemes",
    "errorMessageType": "AReq",
    "messageType": "Erro",
    "messageVersion": "2.2.0"
  }
}

3DS Validation Failures
HTTP Status 400
The request you sent was not a valid 3DS Authenticate Request, address each of the errors.

{
    "status": 400,
    "timestamp": 1629398686,
    "message": "Validation error",
    "cardScheme": "Visa",
    "errors": [
        "browserIP must be a valid IP address",
        "mcc is required when messageCategory is '01'",
        "merchantCountryCode must be 3 characters long",
        "purchaseDate must be in the format YYYYMMDDHHMMSS"
    ],
    "docs": "https://developer.ravelin.com/api/endpoints/3d-secure/authenticate"
}

Timeout reaching directory server
HTTP Status 408 You should retry the request if you receive a timeout, see Retries.

{
    "status": 408,
    "timestamp": 1629400387,
    "cardScheme": "Visa",
    "message": "Ravelin experienced a timeout when sending the authentication request to the directory server."
}

3DS Result could not be found
HTTP Status 404
The threeDSServerTransID in the Result Request could not be found, or it has expired.

{
    "status": 404,
    "timestamp": 1629397969,
    "message": "The 3DS result for the given threeDSServerTransID could not be found"
}

Invalid response received from directory server
HTTP Status 502
The ‘data’ field will contain a 3DS error containing details of the issue Ravelin identified in the directory server’s response. This 3DS error will have been sent to the directory server to notify it of the issue, and is included here for information.

You should restart the 3DS process if you receive a 502 Bad Gateway error, see Retries.

{
    "status": 502,
    "timestamp": 1629400387,
    "cardScheme": "Visa",
    "message": "Ravelin received an invalid response from the directory server. See the 'data' field for the 3DS error message Ravelin has sent to the directory server.",
    "data": {
        "threeDSServerTransID": "c5584543-b67e-5117-bb34-3567ac6a1123",
        "acsTransID": "214a549e-2310-4359-b590-c53a20adcc78",
        "dsTransID": "a3384543-b67e-5117-bb34-4567ac6a1123",
        "errorCode": "203",
        "errorComponent": "S",
        "errorDescription": "Data element not in the required format or value is invalid",
        "errorDetail": "purchaseDate",
        "errorMessageType": "AReq",
        "messageType": "Erro",
        "messageVersion": "2.2.0"
    }
}

3DS error received from directory server
The HTTP Status code will vary depending on the type of 3DS error.
The ‘data’ field will contain the 3DS error Ravelin received from the directory server. The reason for the error could be due to the request content, a 3DS Server issue or a fault with the directory server. This error will have been logged and will be investigated.

If the HTTP status code is 502 or 504 you should restart the 3DS process, see Retries.

{
    "status": 400,
    "timestamp": 1629400387,
    "cardScheme": "Visa",
    "message": "Ravelin received a 3DS error message from the directory server. See the 'data' field for the 3DS error message.",
    "data": {
        "threeDSServerTransID": "c5584543-b67e-5117-bb34-3567ac6a1123",
        "acsTransID": "214a549e-2310-4359-b590-c53a20adcc78",
        "dsTransID": "a3384543-b67e-5117-bb34-4567ac6a1123",
        "errorCode": "203",
        "errorComponent": "D",
        "errorDescription": "Data element not in the required format or value is invalid",
        "errorDetail": "purchaseDate",
        "errorMessageType": "AReq",
        "messageType": "Erro",
        "messageVersion": "2.2.0"
    }
}

Ravelin experienced an internal error
HTTP Status 500
You should retry the request if you receive an internal server error, see Retries.
This will have been logged and will be investigated.

{
    "status": 500,
    "timestamp": 1629397969,
    "message": "Internal Server Error"
}

HTML Error Responses

Under some circumstances the Ravelin 3D Secure API will return errors in an HTML format. These will always be related to an integration issue and should not occur during operation. Several examples are shown below.

Badly formatted GET HTTP Request
HTTP Status 400
GET requests must not contain a body. Ensure you didn’t mean to send a POST request.

400. That’s an error.
Your client has issued a malformed or illegal request.

URL did not use HTTPS
HTTP Status 404
For example, the URL http://pci.ravelin.com/3ds/authenticate is incorrect because it uses http and not https.

404. That’s an error.
The requested URL /3ds/authenticate was not found on this server.

Content-Length Header is missing
HTTP Status 411
All 3D Secure API requests must be sent with a Content-Length header.

400. That’s an error.
POST requests require a Content-length header.

Retries

We have different recommendations for retries depending on the error response HTTP status code.

Timeout - HTTP Status 408
You should immediately retry once if you receive a 408 Timeout error response. You should send the same threeDSServerTransID as used on the original request.

Internal Server Error - HTTP Status 500
You should immediately retry once if you receive a 500 Internal Server Error response. You should send the same threeDSServerTransID as used on the original request.

Bad Gateway - HTTP Status 502
If you receive a 502 Bad Gateway error response you should restart the 3DS process, or end 3DS processing. If you restart the 3DS process you must begin by sending a new Version Request. You must not use the threeDSServerTransID from the original request. A new threeDSServerTransID must be generated. You may need to notify the customer that the 3DS process was restarted.

Gateway Timeout - HTTP Status 504
If you receive a 504 Gateway Timeout error response you should restart the 3DS process, or end 3DS processing. If you restart the 3DS process you must begin by sending a new Version Request. You must not use the threeDSServerTransID from the original request. A new threeDSServerTransID must be generated. You may need to notify the customer that the 3DS process was restarted.

All Other Responses
Do not retry on any other responses. You should investigate the cause of the error. You should notify the customer that 3DS is currently not available.

Feedback