Intro

Authorization Rules are a flexible, Lithic-hosted solution designed to give card programs detailed control over transaction authorizations. By allowing the creation of rules based on high-signal attributes like MCC, country, currency, risk score, and more, they provide a powerful tool for enforcing business-specific authorization logic at the program, account, or card level. Whether you need to block transactions based on geographic location, restrict certain merchants, or apply spending limits, Authorization Rules enable precise decision-making without the complexity of additional infrastructure.

A key feature of Authorization Rules is shadow mode, which allows you to safely test draft rules without impacting live transactions. In shadow mode, rules observe the authorization stream, logging how they would have affected approvals and declines, giving you the ability to fine-tune rules before activating them. Once a draft rule is promoted, it immediately begins affecting transaction outcomes.

In addition to transaction-specific decisioning logic, velocity limits can be defined to control transaction volume or spend over set periods, helping prevent unauthorized usage and enforce compliance policies.

To ensure your rules are performing as expected, performance reports provide detailed insights into approval and decline rates, with specific transaction examples. Reports are delivered asynchronously via webhook, helping you continuously optimize your rule configurations.

Authorization Rules also integrate seamlessly with Lithic’s Authorization Stream Access (ASA), enabling businesses to handle more complex decision-making through a combination of Lithic-hosted rules and custom ASA logic.

Defining Authorization Rules

Rule Configuration

Before diving into the process of drafting and managing Authorization Rules, it's essential to understand the types of rules that can be created, the available options for defining them, and the limitations of different rule templates. Lithic offers various rule configurations to meet your program’s specific authorization logic needs.

Types of Authorization Rules

Authorization Rules can be categorized based on the type of action they enforce on transactions. The two primary types of rules are:

• CONDITIONAL_BLOCK: This rule type allows you to block transactions based on a set of conditions. A transaction will be blocked if it meets all the conditions defined in the rule.

• VELOCITY_LIMIT: These rules place restrictions on the number or value of transactions allowed within a specified time period. Velocity limits help control excessive spending or manage fraud risks by enforcing limits on how frequently or how much a card can be used.

Options for Defining a Conditional Block Rule

A Conditional Block rule lets you block transactions based on a combination of conditions. These conditions help you create granular controls over the authorization process. Below are the available attributes for defining a conditional block rule:

• Merchant Category Code (MCC): You can restrict or allow transactions based on specific MCCs. MCCs represent the type of merchant where the transaction occurs.
• Country: Transactions can be restricted or allowed based on the merchant's country, helping you enforce geographic controls.
• Currency: Control which currencies are allowed for transactions, ensuring compliance with your program’s strategy.
• Merchant ID: Block or allow transactions based on the specific merchant, enabling more refined control over merchant acceptance.
• Descriptor: Regex matching against the merchant descriptor allows filtering of transactions based on the merchant’s name or other text identifiers.
• Liability Shift: You can block or allow transactions depending on whether liability for the transaction has shifted, such as in 3DS-secured transactions.
• PAN Entry Mode: Specify rules based on how the card number was entered (e.g., chip, manual, or contactless).
• Transaction Amount: Define minimum and maximum thresholds for transaction values.
• Risk Score: Use the network risk score to block transactions that exceed a certain risk threshold.

By combining multiple conditions, you can create a precise set of rules tailored to your business needs. For example, you can block high-risk, international transactions over a certain amount, adding layers of security.

Options for Defining a Velocity Limit Rule

A Velocity Limit rule restricts the number or value of transactions within a specified timeframe. These rules can be used to manage spending and prevent excessive usage.

Here are the main options for defining velocity limits:

• Transaction Count Limit: Restrict the number of transactions allowed within a defined interval. For instance, limit a card to 10 transactions per day or 50 per month.
• Amount Limit: Set a maximum total spend allowed within the specified interval. For example, limit a card to $500 per week or $2000 per month.
• Time Intervals: Velocity limits can be defined for various timeframes:
  • Daily, Weekly, Monthly: These intervals reset based on calendar time (e.g., a daily limit resets at midnight).
  • Custom Windows: You can create rolling intervals where the limit resets a certain number of days or hours after the first transaction.

Velocity limits are highly effective in controlling how often or how much a card is used, especially for fraud prevention, managing budgets, or enforcing compliance requirements.

Rule Limitations and Considerations

While Authorization Rules are highly customizable, there are some limitations and best practices to consider when defining your rules:

• Compliance with Card Network Policies: When using block rules such as MCC or country restrictions, ensure that they comply with your cardholder agreement terms. Restrictions beyond what is stated in your agreement may require additional steps to remain compliant with card network policies. If needed, reach out to your Customer Success representative for further assistance.
• Conflict Resolution: When multiple rules apply to a transaction at different entity levels (program, account, or card), the most restrictive rule will take precedence. For instance, if a program-level rule allows transactions in all countries, but a card-level rule restricts transactions to the US, transactions on that card will only be allowed in the US.
• Rule Testing: It is essential to use shadow mode and performance reports to test rule logic before activation. Poorly defined rules can result in unintended transaction declines, especially when combining multiple conditions.
• Velocity Limit Computation: While velocity limits are enforced based on authorized and settled volume, they are not recommended to be used for balance or reconciliation-level accuracy. Velocity limit computation is eventually consistent - which may result in exceeding the limit in some edge cases. For balance or reconciliation-level accuracy, please see our balances product for more detail.

Creating and Managing Authorization Rules

Drafting a New Authorization Rule

Drafting a new authorization rule is the first step in creating custom authorization logic for your program, account, or card. When you draft a rule, it runs in shadow mode, meaning it observes live transactions without affecting authorization outcomes. This allows you to see how the rule would perform in real-world conditions before fully activating it.

Create a Draft Rule

To draft a new rule, use the POST /v2/auth_rules endpoint. You’ll specify the parameters that define your rule, such as the transaction attributes (e.g., MCC, country, risk score) that will be evaluated. The rule will be created in draft mode and will begin running in shadow mode immediately, allowing you to measure its impact without affecting live authorizations.

Example Request:

{
  "program_level": true,
  "type": "CONDITIONAL_BLOCK",
  "parameters": {
    "conditions": [
      {
        "attribute": "MCC",
        "operation": "IS_ONE_OF",
        "value": ["3000", "3001"]
      }
    ]
  }
}

📘

To see all information about creating authorization rules, see the full API specification here.

In this example, the rule is created to block transactions based on specific Merchant Category Codes (MCC) and is applied at the program level. You can adjust the parameters to match your specific use case, applying rules at the account or card level if necessary.

Test in Shadow Mode

Once the rule is created, it runs in shadow mode. This means the rule will evaluate transactions in real-time, logging how it would have affected transaction outcomes—whether it would have approved or declined them—but it will not yet influence live transactions. During this phase, you can measure the rule's performance by observing its behavior through the performance reports feature, which will be covered in the next section.

Using shadow mode is essential to ensuring your rule functions as intended before promoting it to live status, minimizing the risk of unintended transaction declines or approvals.

Best Practices

• Thorough testing: Use shadow mode to evaluate the rule’s behavior across different transaction types and scenarios, ensuring it performs as expected before promotion.
• Iterate as needed: Authorization logic can evolve. Make use of drafts to refine rules incrementally based on performance data and new business requirements.
• Keep rule interactions in mind: When drafting multiple rules, consider how they may interact to avoid unintended outcomes when they are activated.

Measuring an Authorization Rule

Once a draft authorization rule has been created and is running in shadow mode, it's important to measure its performance before promoting it to active status. Lithic provides performance reports that give insights into how a rule would impact transactions, whether in draft or active mode. These reports help you assess the effectiveness of the rule by tracking how it influences transaction approvals and declines.

Request a Performance Report

To measure an authorization rule’s performance, you can request a report using the POST /v2/auth_rules/{auth_rule_token}/report endpoint. These performance reports are delivered asynchronously via webhook and include metrics such as the number of approved and declined transactions, as well as specific examples of affected transactions.

Example Request:

POST /v2/auth_rules/{auth_rule_token}/report

📘

To see all information about requesting performance reports, see the full API specification here.

This request asks for a performance report for a given rule token over the specified time range. Reports can be generated for any rule in draft or active mode, allowing you to evaluate both test and live configurations.

Receive Performance Data

Once the report is generated, it will be delivered through a webhook with the event type auth_rules.performance_report.created. The report contains key statistics such as the number of transactions approved or declined by the rule and includes examples of individual transactions for further analysis.

Example Response:

{
  "auth_rule_token": "50800f8a-4ed2-416f-9f70-ad504d7c90d5",
  "report_token": "e19d7fd5-cc23-4cb9-acca-0c4effaf5921",
  "from": "2024-09-01T00:00:00Z",
  "to": "2024-09-30T23:59:59Z",
  "current_version_statistics": {
    "approved": 3456,
    "declined": 123,
    "examples": [
      {
        "event_token": "d0b52bd2-f003-4a03-9ffc-db36fc06f9e5",
        "timestamp": "2024-09-15T12:00:00Z",
        "approved": true
      },
      {
        "event_token": "8dc5b7de-03c3-4ed3-b444-7dcf9f5a9fbb",
        "timestamp": "2024-09-18T14:30:00Z",
        "approved": false
      }
    ]
  },
  "draft_version_statistics": {
    "approved": 234,
    "declined": 45,
    "examples": [
      {
        "event_token": "2870db90-21c4-4159-9344-56fb2cf947ba",
        "timestamp": "2024-09-20T10:15:00Z",
        "approved": true
      },
      {
        "event_token": "6918da4b-8dd5-4a37-a9d8-d3e047cfdb7a",
        "timestamp": "2024-09-25T11:45:00Z",
        "approved": false
      }
    ]
  }
}

📘

To see all information about the webhook event for performance reports, see the full API specification here.

This example response shows statistics for both the current active version and the draft version of the rule, allowing you to compare how each is performing. If you're drafting a rule for the first time and no active version yet exists, only the draft version statistics will be populated.

Best Practices for Measuring Rules

• Monitor regularly: Request performance reports frequently to keep track of how your rule evolves over time, especially as transaction patterns change.
• Review transaction examples: Use the examples provided in the report to review specific transactions affected by the rule. This can help refine rule parameters for improved performance.
• Compare draft and active versions: Analyze the data from both draft and active rules to ensure you are optimizing your authorization logic effectively across all versions.

Promoting an Authorization Rule

Once you have measured the performance of your draft rule and are confident in its effectiveness, the next step is to promote the rule from shadow mode to active mode. Promoting a rule makes it immediately live in the authorization stream, meaning it will start impacting real transactions according to the logic you have defined.

Promote the Rule

To promote a rule, use the POST /v2/auth_rules/{auth_rule_token}/promote endpoint. This endpoint will take the parameters of the draft version and apply them to the active authorization rule, replacing any existing active rule for the specified token. Once promoted, the rule begins affecting authorizations in real time.

Example Request:

POST /v2/auth_rules/{auth_rule_token}/promote

📘

To see all information about promoting an authorization rule, see the full API specification here.

There are no additional parameters required in the request body. The promotion process will simply transfer the draft parameters to the active rule, and the draft will be cleared.

What Happens During Promotion

Promoting a rule makes the draft parameters the active rule, replacing the existing active rule for the specified token. Once promoted, the draft rule ceases to exist, and its parameters are applied to the active authorization stream. This means the rule will now affect authorizations in real-time based on the logic you have defined.

It’s important to note that once a rule is promoted, the details of the previous active rule are no longer recoverable, as they are overwritten by the promoted draft. Make sure to measure and verify the draft’s performance thoroughly before promotion to avoid unintended results.

Best Practices for Promoting Rules

• Verify thoroughly: Ensure the draft rule has been adequately tested and measured in shadow mode before promotion, as the active rule will immediately begin affecting live authorizations.
• Document changes: Keep a record of rule promotions to track changes and adjustments made to your authorization logic over time.
• Monitor post-promotion: After promotion, continue to monitor the rule’s performance using performance reports to ensure it is behaving as expected in live transactions.

Once a rule is promoted, it becomes the active authorization logic for the specified entities (program, account, or card), and will continue to impact transactions until it is modified or disabled.

Disabling an Authorization Rule

Disabling an authorization rule is the process of stopping the rule from impacting the live authorization stream. When a rule is disabled, it no longer applies to transactions, but the rule itself remains in the system for future reference or modification.

Disable the Rule

To disable a rule, use the PATCH /v2/auth_rules/{auth_rule_token} endpoint, setting the rule's state to INACTIVE. This will prevent the rule from affecting authorization decisions, but the rule itself will remain in the system for future reactivation or editing.

Example Request:

PATCH /v2/auth_rules/{auth_rule_token}

{
  "state": "INACTIVE"
}

📘

To see all information about updating an authorization rule, see the full API specification here.

This request changes the state of the authorization rule to INACTIVE, effectively disabling it. The rule will no longer affect transaction authorizations, but can be modified if necessary.

Clearing Drafts

In addition to disabling active rules, you can clear a draft rule by overwriting it with a blank rule template. This is useful if the draft version of a rule no longer needs to be tested in shadow mode or if you want to reset the rule's logic.

Example Request to Clear a Draft:

POST /v2/auth_rules/{auth_rule_token}/draft

{
  "parameters": null
}

📘

To see all information about clearing drafts, see the full API specification here.

This request resets the draft parameters, effectively clearing the draft version of the rule without affecting the active rule.

Best Practices for Disabling Rules

• Document deactivations: Keep a record of when and why rules are disabled to avoid confusion when reactivating or modifying them later.
• Reassess before reactivation: If a rule is re-enabled after a long period of inactivity, ensure the logic is still relevant to current transaction patterns.
• Use soft deactivation: Disabling a rule is non-destructive, making it a good choice for temporarily pausing rules without losing their configurations.

By using the disable and draft-clear features, you have full flexibility to pause, reset, or deactivate authorization logic without losing your work. This allows for easy adjustments and future reactivations when necessary.

Retrieving Existing Authorization Rules

After creating, drafting, or promoting an authorization rule, you may want to retrieve and review the existing rules in your system. Lithic provides endpoints for listing all authorization rules under a program, as well as fetching the details of a specific rule by its token. These endpoints help you manage and review active, draft, or disabled rules across your card program.

Listing All Authorization Rules

To retrieve a list of all authorization rules under your program, use the GET /v2/auth_rules endpoint. This endpoint returns details of all authorization rules applied at the program, account, or card level. It is especially useful for reviewing the status and parameters of multiple rules in one query.

Example Request:

GET /v2/auth_rules

You can filter the response by parameters like account_token or card_token to retrieve only the rules associated with specific accounts or cards.

Example Response:

{
  "data": [
    {
      "auth_rule_token": "a4e8dc9a-f821-4365-b6a9-a6219b105b6d",
      "program_level": true,
      "parameters": {
        "conditions": [
          {
            "attribute": "MCC",
            "operation": "IS_ONE_OF",
            "value": ["3000", "3001"]
          }
        ]
      },
      "state": "ACTIVE"
    },
    {
      "auth_rule_token": "a25eab6a-7cc1-48e1-b7cc-eb4674fb8c7e",
      "program_level": false,
      "account_tokens": ["a1b2c3d4"],
      "parameters": {
        "conditions": [
          {
            "attribute": "COUNTRY",
            "operation": "IS_NOT_ONE_OF",
            "value": ["USA", "CAN"]
          }
        ]
      },
      "state": "INACTIVE"
    }
  ],
  "has_more": false
}

📘

To see all information about listing authorization rules, see the full API specification here.

This example response shows two authorization rules: one that is active at the program level and another that is inactive and applied to a specific account.

Fetching an Authorization Rule by Token

To retrieve the details of a specific authorization rule, use the GET /v2/auth_rules/{auth_rule_token} endpoint. This request returns detailed information about the rule, including its parameters, current state (active or inactive), and any draft versions that may exist.

Example Request:

GET /v2/auth_rules/{auth_rule_token}

📘

To see all information about fetching an authorization rule by token, see the full API specification here.

This is useful for checking the configuration of a specific rule before making modifications or reviewing its status in the authorization stream.

Best Practices for Retrieving Rules

• Filter results: Use filters like account_token or card_token to narrow down the list of rules and make it easier to manage specific entities.
• Review regularly: Regularly review active and inactive rules to ensure your authorization logic remains relevant and aligned with your business needs.

By retrieving and reviewing existing authorization rules, you can effectively manage and maintain your program’s authorization logic over time.

Conclusion

Authorization Rules provide a powerful and flexible way to manage transaction authorization across your program, account, or card levels. Whether you’re drafting new rules in shadow mode, measuring their impact with performance reports, or promoting and disabling rules as your business evolves, Lithic’s Authorization Rules give you the control you need to enforce complex authorization logic efficiently.

The integration of Authorization Rules with Lithic’s infrastructure removes the need to manage external systems, offering a streamlined, scalable solution that adapts to your program’s needs. For more complex decision-making, Authorization Rules can also work alongside Lithic’s Authorization Stream Access (ASA), giving you the flexibility to combine built-in rule logic with fully customizable decisioning.

For detailed information about any of the endpoints mentioned, please refer to the full API documentation linked throughout this guide.

If you have any questions or need further assistance, feel free to reach out to our support team by using the HELP button in your Lithic Dashboard.

Authorization Rules FAQ

📘

Deprecated versions:

Authorization Rules V2 (described in this guide) supersedes previous Auth Rules V1 functionality. Auth Rules V1 is now deprecated. To review the guide page for deprecated Auth Rules V1, see here.