3DS Reasons

Overview

When processing 3D Secure (3DS) transactions, the API returns a numeric reason code in the tds object that provides detailed information about the outcome of the authentication process. This guide maps each reason code to its meaning.

Reason Code Reference

Code	Meaning	Description
1	CARD_AUTHENTICATION_FAILED	Card authentication failed.
2	UNKNOWN_DEVICE	The device is not recognized by the issuer.
3	UNSUPPORTED_DEVICE	The device type is not supported for 3DS.
4	EXCEEDS_AUTHENTICATION_FREQUENCY_LIMIT	The cardholder has exceeded their authentication frequency limit set by their issuing bank.
5	EXPIRED_CARD	The card has expired or an incorrect expiry date was entered.
6	INVALID_CARD_NUMBER	The cardholder has entered an invalid card number.
7	INVALID_TRANSACTION	The cardholder's issuing bank will not authenticate the transaction at this time.
8	NO_CARD_RECORD	The card number is not recognized by the issuing bank.
9	SECURITY_FAILURE	The cardholder's issuing bank has encountered a security error.
10	STOLEN_CARD	The card has been reported stolen.
11	SUSPECTED_FRAUD	This transaction is suspected to be fraudulent.
12	TRANSACTION_NOT_PERMITTED_TO_CARDHOLDER	The issuing bank does not permit the cardholder to complete this type of transaction.
13	CARDHOLDER_NOT_ENROLLED_IN_SERVICE	The cardholder is not enrolled in the 3DS service.
14	TRANSACTION_TIMED_OUT_AT_THE_ACS	The transaction timed out at the Access Control Server (ACS).
15	LOW_CONFIDENCE	The cardholder's issuing bank does not have confidence to approve the transaction.
16	MEDIUM_CONFIDENCE	The cardholder's issuing bank does not have enough confidence to approve the transaction.
17	HIGH_CONFIDENCE	The cardholder's issuing bank has high confidence in approving the transaction.
18	VERY_HIGH_CONFIDENCE	The cardholder's issuing bank has very high confidence in approving the transaction.
19	EXCEEDS_ACS_MAXIMUM_CHALLENGES	The cardholder has exceeded the maximum number of challenges allowed by the ACS.
20	NON_PAYMENT_TRANSACTION_NOT_SUPPORTED	Non-payment transactions are not supported.
21	THREERI_TRANSACTION_NOT_SUPPORTED	3-RI transactions are not supported.
22	ACS_TECHNICAL_ISSUE	There was a technical issue after the cardholder completed the challenge.
23	DECOUPLED_AUTHENTICATION_REQUIRED_BY_ACS	Decoupled authentication is required by the ACS.
24	DECOUPLED_MAX_EXPIRY_TIME_EXCEEDED	The maximum expiry time for decoupled authentication has been exceeded.
25	INSUFFICIENT_TIME_TO_AUTHENTICATE	There was insufficient time to authenticate the transaction.
26	AUTHENTICATION_ATTEMPTED_BUT_NOT_PERFORMED	Authentication was attempted but not performed.
27	SCHEME_STATUS_REASON	Authentication has failed due to a reason determined by the card scheme.
28	ERROR_RECEIVED_DOWNSTREAM	An error was received from a downstream system.

Example Response

Here's an example of a failed 3DS transaction with a reason code:

{
  "transaction_id": "a7e3fde5-5b83-44f4-9915-782bc7121717",
  "status": "tds_failed",
  "reason": "15",
  "tds": {
    "status": "failed",
    "reason": 15
  }
}

In this example, reason code 15 indicates LOW_CONFIDENCE — the cardholder's issuing bank does not have confidence to approve the transaction.

Handling 3DS Failures

When you receive a tds_failed status with a reason code:

Check the reason code against this reference to understand what happened
Inform the cardholder — Some reasons (like expired card or stolen card) require immediate action
Retry if appropriate — Transient issues like ACS_TECHNICAL_ISSUE (22) may succeed on retry
Contact support — For persistent issues, reach out to our support team with the transaction ID and reason code