Overview

A conditional action rule (CONDITIONAL_ACTION rule type) takes an action on a transaction when it matches a set of conditions you define. It is the most common Authorization Rule type and is available on every event stream.

On the AUTHORIZATION event stream a conditional action rule can either decline a transaction or challenge it (trigger an SMS-based step-up authentication). The available actions depend on the event stream:

This page covers conditional action rules on the AUTHORIZATION event stream. For the other streams, see 3DS Authentication Rules, Tokenization Rules, and ACH Auth Rules.

📘

The CHALLENGE action on the AUTHORIZATION event stream (Authorization Challenges) is part of Lithic Fraud Command. See Authorization Challenges for details. The DECLINE action is available to all Authorization Rules clients.

Defining a Condition

Each condition is made up of three parts:

1. Attribute: the characteristic of the transaction to evaluate (for example, MCC, country, or currency)
2. Operation: the logical comparison to apply (for example, IS_ONE_OF or IS_GREATER_THAN)
3. Value: the value or values the operation compares against (for example, "USD" or 500)

For example, a US card program that wants to block all foreign currency transactions could define a rule with the DECLINE action and a single condition:

• Attribute: CURRENCY
• Operation: IS_NOT_ONE_OF
• Value: ["USD"]

This rule declines any transaction where the merchant currency is not USD.

Attributes

The attributes below are a representative selection of the high-signal attributes available on the AUTHORIZATION event stream:

• Merchant Category Code (MCC): a four-digit number listed in ISO 18245 that classifies a business by the goods or services it provides
• Country: the country of the card acceptor entity
• Currency: the 3-character alphabetic ISO 4217 code for the merchant currency of the transaction
• Merchant ID: the unique alphanumeric identifier for the payment card acceptor (merchant)
• Descriptor: the short description of the card acceptor
• Transaction Amount: the amount of the transaction in the cardholder billing currency
• Risk Score: the network-provided score assessing the risk level associated with a given authorization
• PAN Entry Mode: the method by which the cardholder's primary account number (PAN) was entered
• Liability Shift: indicates whether chargeback liability shift to the issuer applies to the transaction
• Card State: the current state of the card associated with the transaction
• Wallet Type: for transactions using a digital wallet token, the source of the token
• Address Match: the result of address verification (AVS) for the transaction
• Transaction Initiator: indicates who initiated the transaction (cardholder, merchant, or unknown)

📘

This is not the full list. Lithic adds new decisionable attributes regularly. For the complete, current set of attributes and their valid values, see the Auth Rules API specification.

Behavioral Attributes

In addition to the per-transaction attributes above, Authorization Rules can evaluate behavioral attributes derived from a card's or account's recent history, such as transaction and decline counts over trailing windows, spend z-scores, first-seen signals (new country, new MCC, first transaction), and travel speed between transactions.

📘

Behavioral attributes are part of Lithic Fraud Command. They require a parameters object (for example, a scope and interval) in addition to the attribute. See Contextual Rule Features for the full set and how to configure them.

Operations

The operation determines how the attribute value is compared against your configured value.

List Operations

Use with an array of strings as the value. Applies to string attributes like COUNTRY, CURRENCY, and PAN_ENTRY_MODE.

Numeric Operations

Use with a number as the value. Applies to attributes like TRANSACTION_AMOUNT, CASH_AMOUNT, and RISK_SCORE.

String Pattern Operations

Use with a regular expression string as the value.

The MATCHES and DOES_NOT_MATCH operations are useful for matching merchant descriptors that vary in formatting:

• Patterns follow standard regex syntax
• Matching is case-sensitive by default
• Patterns match against the full attribute value

📘

Additional operations are available for other attribute types and event streams, including date operations (IS_BEFORE, IS_AFTER) and list-membership operations (CONTAINS_ANY, CONTAINS_ALL, CONTAINS_NONE). See the Auth Rules API specification for which operations apply to each attribute.

Combining Conditions

Conditional action rules can be combined to express complex logic.

Multiple Conditions in One Rule (AND)

A transaction is actioned only if it matches all of the conditions in a rule. For example, to block most foreign currency transactions while still allowing those with a very low network risk score, define a single rule with two conditions:

• Condition 1: CURRENCY IS_NOT_ONE_OF ["USD"]
• Condition 2: RISK_SCORE IS_GREATER_THAN 200

This rule declines transactions that are in a foreign currency and have a network risk score greater than 200. A foreign currency transaction with a risk score of 200 or below is not declined, because it does not match all the conditions.

Multiple Rules Per Entity (OR)

You can define multiple rules at each entity level (program, account, and card). To decline a transaction when any condition matches, create separate rules, each with a single condition:

• Rule 1: CURRENCY IS_NOT_ONE_OF ["USD"]
• Rule 2: RISK_SCORE IS_GREATER_THAN 200

With these two rules, Lithic declines transactions that are in a foreign currency or have a network risk score above 200.

By combining multi-condition rules (AND) with multiple rules per entity (OR), you can design authorization logic that precisely enforces your program's requirements, all hosted on Lithic's infrastructure.

Example Request

The following request creates a program-level rule that declines transactions at gambling-related MCCs:

{
  "name": "Block gambling MCCs",
  "program_level": true,
  "type": "CONDITIONAL_ACTION",
  "event_stream": "AUTHORIZATION",
  "parameters": {
    "action": "DECLINE",
    "conditions": [
      {
        "attribute": "MCC",
        "operation": "IS_ONE_OF",
        "value": ["7801", "7802", "7995"]
      }
    ]
  }
}

📘

For the full request schema, see the Create Auth Rule API.

Next Steps

• Authorization Rule Lifecycle: draft, test in shadow mode, promote, and disable rules
• Analytics and Observability: measure rule impact and interpret decline results
• Velocity Limit Rules: restrict transaction count or spend over time