Transaction Monitoring Rules

Overview

Transaction Monitoring rules run after a transaction has been authorized. They are built on the same rules engine as Authorization Rules, so the rule type system, lifecycle, and tooling carry over.

Two rule outcomes are available:

• Tagging rules apply structured TAG actions to a transaction. Tags are key/value annotations with an optional human-readable explanation. Tags are available to downstream rules and to analysts reviewing a case.
• Case creation rules emit a CREATE_CASE action that opens an investigation against the transaction's card or account. Cases route to a queue where an analyst picks them up for review.

Both outcomes are produced by the same rule type, CARD_TRANSACTION_UPDATE. Rules can be authored as conditional rules built from attributes and operations, or as custom TypeScript code for logic that needs arithmetic, fuzzy matching, or external libraries (see Custom Code Rules). The actions a rule emits determine whether it tags, opens cases, or does both.

How rules evaluate

Each post-authorization transaction update triggers a two-phase evaluation:

1. Tagging phase. All active tagging rules run first. Each rule that matches the transaction can emit one or more TAG actions. Tags from conditional-template tagging rules are merged onto the transaction before the next phase begins.
2. Case creation phase. All active case creation rules run against the (now tagged) transaction. A rule that matches can emit a CREATE_CASE action, which either opens a new case or appends the transaction to an existing collecting case for the same rule and entity.

Because tagging runs first, case creation rules can reference tags applied earlier in the same evaluation cycle. For example, a tagging rule can mark high_risk=true based on merchant context, and a case creation rule can match only when three or more transactions tagged high_risk=true accumulate on a card in 24 hours.

Rules are evaluated asynchronously and do not interrupt authorization. To decline or challenge a transaction in flight, use Authorization Rules instead.

Tag merging and deduplication

Multiple tagging rules can apply to the same transaction. Tags with different keys are all kept and attached side by side. When two or more rules emit the same tag key with different values, Lithic keeps one value and discards the rest. The choice is deterministic: the value that sorts lowest in lexicographic (byte-order) string comparison wins.

The optional explanation on a tag is stored alongside the rule evaluation, not on the tag attached to the transaction. To inspect why a tag was applied to a specific transaction, retrieve the evaluation via the Rule Results API.

Rule lifecycle

Monitoring rules follow the same lifecycle as Authorization Rules. A rule has one or more versions, and each version is in one of three states:

Promote a version from SHADOW to ACTIVE by issuing a state change against it. See Authorization Rules for the full lifecycle walkthrough including draft management, shadow evaluation, and approvals.

Action types

Each evaluated rule may emit zero or more actions. For monitoring rules, two action types are supported.

Tag

{
  "type": "TAG",
  "key": "high_risk",
  "value": "true",
  "explanation": "MCC 5411 flagged as high-risk category"
}

Create case

{
  "type": "CREATE_CASE",
  "scope": "CARD",
  "queue_token": "9e1d4d4e-3e2f-4d72-8a39-ec0e0e7fef94",
  "explanation": "3+ high-risk transactions on this card within 24 hours"
}

When a CREATE_CASE action runs, Lithic looks up existing cases for the same rule and entity:

• If no case exists for the rule and entity, a new case is opened with status OPEN and the triggering transaction attached.
• If a case exists with status OPEN, the triggering transaction is appended to it and no new case is created.
• If the most recently updated case for the rule and entity has transitioned out of OPEN, the rule re-evaluates against only the unreviewed activity. Velocity windows are clamped to start no earlier than the timestamp when that existing case left OPEN, so transactions already on the previous case are not double-counted. If the clamped re-evaluation still matches, a new case is opened with status OPEN and the triggering transaction attached. Otherwise no new case is created.

This keeps a single case as the working surface for an analyst even as new activity continues to land on the same entity, while still letting the rule open a fresh case for the next genuine pattern after the previous one is finalized.

Examples

The two examples below show the rule payloads for the most common monitoring shapes:

1. A conditional tagging rule that tags transactions at high-risk MCC codes.
2. A velocity case creation rule that opens a case when a card accumulates multiple transactions carrying the tag above within a rolling window.

📘

Examples may go out of date as the API evolves. For the latest and most accurate request shapes, refer to the Authorization Rules API spec.

{
  "name": "tag-high-risk-merchant",
  "event_stream": "CARD_TRANSACTION_UPDATE",
  "type": "CONDITIONAL_ACTION",
  "parameters": {
    "action": {
      "type": "TAG",
      "key": "merchant_risk",
      "value": "high"
    },
    "conditions": [
      {
        "attribute": "MCC",
        "operation": "IS_ONE_OF",
        "value": ["5411", "5912", "7995"]
      }
    ]
  }
}

{
  "name": "high-risk-merchant-velocity",
  "event_stream": "CARD_TRANSACTION_UPDATE",
  "type": "CONDITIONAL_ACTION",
  "parameters": {
    "action": {
      "type": "CREATE_CASE",
      "scope": "CARD",
      "queue_token": "9e1d4d4e-3e2f-4d72-8a39-ec0e0e7fef94"
    },
    "conditions": [
      {
        "attribute": "SPEND_VELOCITY_COUNT",
        "operation": "IS_GREATER_THAN",
        "parameters": {
          "scope": "CARD",
          "period": { "type": "DAY" },
          "filters": {
            "include_tags": { "merchant_risk": "high" }
          }
        },
        "value": 2
      }
    ]
  }
}

Limitations

• Monitoring rules run asynchronously and cannot interrupt a transaction in flight.
• Tag values are deduplicated by string comparison: the lowest value wins on collision. Plan tag values accordingly.
• Tags emitted by custom-code rules do not propagate to the case-creation phase within the same evaluation cycle. Conditional-template tagging rule tags do propagate.
• The CREATE_CASE action's scope parameter supports CARD and ACCOUNT. Business-account scope is not currently supported.
• A CREATE_CASE action requires the destination queue_token to exist before the rule promotes to ACTIVE. Create queues first.

Next steps

• Case Management: Work the cases that monitoring rules open.
• Authorization Rules: The full rule lifecycle, including shadow state, promotion, and backtesting.
• Custom Code Rules: Author TypeScript rules for cases that conditional templates can't express.
• Contextual Rule Features: Reference historical card and account signals from inside a rule.