Guides
StatusDashboard

3DS Authentication Rules

Learn how to customize 3DS decisioning logic using Lithic 3DS Auth Rules

Diagram showing 30+ data fields flowing into a rules-based decision engine that outputs approve, deny, or challenge decisions.
📘

3DS Authentication Rules require enrollment in Lithic's 3DS service. Rules with CHALLENGE actions additionally require a challenge orchestration model to be configured. Learn more about enabling Lithic 3DS

Overview

3DS Authentication Rules enable your organization to define custom logic for 3DS authentication decisions based on transaction attributes. These rules evaluate authentication requests against configurable conditions and can automatically decline transactions or trigger challenge flows when specific criteria are met.

Authentication rules operate as an additional control layer that works with both Lithic Decisioning and Customer Decisioning models. Rules are evaluated during the 3DS authentication flow and can enforce stricter controls than the base decisioning model, but cannot override decline decisions made by other systems.

How Authentication Rules Work

When a 3DS authentication request arrives:

  1. The authentication data is evaluated against all active authentication rules in parallel
  2. Rules check transaction attributes against their configured conditions
  3. If conditions match, the rule executes its defined action (decline or challenge)
  4. The strictest decision across all evaluations is applied
  5. The final authentication response is sent through the network

Authentication rules follow a "most restrictive" principle: if any rule declines an authentication, the transaction is declined regardless of other rule or model decisions. Similarly, if a rule triggers a challenge, the authentication proceeds to a challenge flow unless another rule declines it.

For example, consider two rules: one configured to challenge authentications with risk scores greater than 600, and another configured to decline authentications with risk scores greater than 800. When an authentication is processed with a risk score of 850, both rules evaluate as true. Since authentication rules apply the strictest decision, the authentication is declined rather than challenged due to decline being the stricter decision.

Rule Configuration

Rule Types

3DS Authentication Rules use the CONDITIONAL_ACTION rule type with the event_stream set to THREE_DS_AUTHENTICATION. These rules can take one of two actions:

  • DECLINE: Reject the authentication request
  • CHALLENGE: Initiate a challenge flow (requires challenge orchestration to be configured)

Targetable Attributes

Rules can evaluate authentications based on the following attributes:

  • MCC: Merchant Category Code
  • COUNTRY: Country of card acceptor
  • CURRENCY: Transaction currency
  • MERCHANT_ID: Unique alphanumeric merchant identifier
  • DESCRIPTOR: Short description of card acceptor
  • TRANSACTION_AMOUNT: Transaction amount in cents
  • RISK_SCORE: Network-provided authentication risk score (Mastercard only)
  • MESSAGE_CATEGORY: Authentication category type
  • ADDRESS_MATCH: Result of address verification (AVS) for the transaction
📘

For the full list of targetable attributes, please review the Auth Rules API specification.

Operations

Each condition supports these operations:

  • IS_ONE_OF / IS_NOT_ONE_OF: Match against a list of values
  • MATCHES / DOES_NOT_MATCH: Regex pattern matching
  • IS_GREATER_THAN / IS_LESS_THAN: Numeric comparisons

Scope Levels

Authentication rules can be applied at three levels:

  • Program Level: Applies to all cards in your program
  • Account Level: Applies to specific account tokens
  • Card Level: Applies to specific card tokens

Program-level rules can exclude specific cards or accounts using the excluded_card_tokens, excluded_account_tokens, or excluded_business_account_tokens parameter.

Integration with Decisioning Models

With Lithic Decisioning

When used with Lithic Decisioning, authentication rules provide additional control over Lithic's fraud model decisions. Rules can:

  • Decline authentications that Lithic's model would approve
  • Trigger challenges for transactions Lithic would approve without challenge

This allows organizations to enforce specific business policies or risk tolerances stricter than Lithic's baseline model.

All authentication rules, including the Lithic Decisioning model, are evaluated in parallel and the strictest decision is applied to the authentication. Because of this, 3DS auth rules cannot be used to approve authentications that Lithic's model declines.

With Customer Decisioning

When used with Customer Decisioning, authentication rules can act as a safety net or policy enforcement layer. Rules evaluate independently of your decisioning endpoint and can:

  • Enforce consistent policies across all authentications
  • Act as a fallback if your endpoint times out
  • Implement quick policy changes without modifying endpoint logic

The final authentication decision applies the strictest outcome from both your endpoint and active rules.

Testing and Validation

Draft Versions

Authentication rules support draft versions, allowing you to create and test rule configurations before activation. Draft rules:

  • Run in shadow mode during evaluation
  • Generate performance data without affecting live transactions
  • Can be promoted to active status after validation

Performance Reports

Performance reports provide daily statistics on how each version of a rule evaluated authentications:

GET /v2/auth_rules/{auth_rule_token}/report

Each day's statistics include, per rule version, an action_counts map of action type (such as DECLINE or CHALLENGE) to the number of times it was taken, with non-actioned evaluations counted under NO_ACTION. See Analytics and Observability for the full response shape.

Backtesting

Backtesting evaluates rules against historical transaction data to show how a rule would have performed on past authentications:

POST /v2/auth_rules/{auth_rule_token}/backtests
📘

Backtesting is part of Lithic Fraud Command. See Backtesting Authorization Rules.

Example Use Cases

Challenge High-Risk Merchant Categories

{
  "program_level": true,
  "type": "CONDITIONAL_ACTION",
  "event_stream": "THREE_DS_AUTHENTICATION",
  "parameters": {
    "action": "CHALLENGE",
    "conditions": [
      {
        "attribute": "MCC",
        "operation": "IS_ONE_OF",
        "value": ["5967", "7995", "5816"]
      }
    ]
  }
}

Challenge Transaction Amount Thresholds

{
  "program_level": true,
  "type": "CONDITIONAL_ACTION",
  "event_stream": "THREE_DS_AUTHENTICATION",
  "parameters": {
    "action": "CHALLENGE",
    "conditions": [
      {
        "attribute": "TRANSACTION_AMOUNT",
        "operation": "IS_GREATER_THAN",
        "value": 100000
      }
    ]
  }
}

Decline High-Risk Country Blocks

{
  "program_level": true,
  "type": "CONDITIONAL_ACTION",
  "event_stream": "THREE_DS_AUTHENTICATION",
  "parameters": {
    "action": "DECLINE",
    "conditions": [
      {
        "attribute": "COUNTRY",
        "operation": "IS_ONE_OF",
        "value": ["XYZ", "ABC"]
      }
    ]
  }
}

Example Implementation Process

  1. Design rule logic: Identify transaction patterns requiring additional controls
  2. Create draft rules: Use the Create Auth Rule API to create rules in draft state
  3. Run backtests: Validate rule impact using historical data
  4. Monitor performance: Review performance reports during shadow mode operation
  5. Promote to active: Use the Promote Auth Rule API to activate validated rules
  6. Ongoing monitoring: Track rule performance and adjust as needed

For complete API specifications and additional rule types, see the Auth Rules API documentation.