Tokenization Rules

Tokenization Rules give card programs control over whether a card can be added to a digital wallet (Apple Pay, Google Pay, Samsung Pay, etc.). They operate on the TOKENIZATION event stream within the Authorization Rules framework, using the same draft, shadow mode, and promote lifecycle as other rule types.

📘

Tokenization Rules are part of Lithic Fraud Command. Contact your Lithic account team to enable Fraud Command for your program.

When to Use Tokenization Rules

Lithic offers two base models for tokenization decisioning:

• Lithic Tokenization Decisioning: Lithic decisions on tokenizations on your behalf, generally aligned with the wallets' recommendations.
• Customer Tokenization Decisioning: You host a responder endpoint that receives tokenization requests and returns a decision, similar to Auth Stream Access (ASA).

Tokenization Rules can be layered on top of either model to add attribute-based controls maintained on Lithic's infrastructure. Rules are defined via the API or the Lithic Dashboard.

When rules are used alongside Customer Tokenization Decisioning, Lithic evaluates Tokenization Rules first, then forwards the request to your responder if the rules did not decline it.

Choose Tokenization Rules when you want to:

• Block tokenizations from specific wallet providers or channels
• Require two-factor authentication based on wallet risk scores
• Enforce card state restrictions on tokenizations (e.g., block paused cards)
• Implement tokenization controls without building or maintaining a responder endpoint

How Tokenization Rules Work

Tokenization rules primarily use the CONDITIONAL_ACTION rule type with the event_stream set to TOKENIZATION. For advanced use cases, TYPESCRIPT_CODE rules are also supported on this event stream. When a tokenization request arrives (when a cardholder adds a card to a digital wallet or a merchant stores a card on file), Lithic evaluates all applicable tokenization rules in sequence. If no rules match, the request passes through to the next step in the evaluation chain.

The evaluation chain follows a strict precedence:

1. Wallet recommendation: The digital wallet provider (Apple, Google, Samsung) sends a recommended decision. If the wallet recommends declining, the request is declined regardless of any other rules.
2. Lithic Tokenization Decisioning: Lithic applies its own tokenization decisioning logic on your behalf, generally aligned with the wallets' recommendations. See Tokenization Decisioning by Lithic for details.
3. Your Tokenization Rules: Your configured tokenization rules are evaluated. If any rule's conditions match, its action (DECLINE or REQUIRE_TFA) is applied.
4. Tokenization Decisioning Responder (if configured): If the request was not declined by rules, it is forwarded to your responder for custom decisioning.

🚧

Lithic will never allow a more permissive tokenization decision than what the digital wallet recommends. Your rules can make decisions more restrictive (e.g., declining a request the wallet would have approved, or requiring TFA when the wallet recommended approval) but cannot override a wallet's decline.

Attributes

Tokenization rules evaluate conditions based on attributes specific to the tokenization request. These are distinct from the attributes available on the AUTHORIZATION event stream.

📘

Check the API spec for the most up-to-date list of attributes and their valid values.

Request Context Attributes

Wallet Risk Signal Attributes

Card State Attributes

All attributes support the same conditional operators available for authorization rules: IS_ONE_OF, IS_NOT_ONE_OF, IS_GREATER_THAN, IS_LESS_THAN, CONTAINS_ANY, and others. See the API spec for the full list.

Actions and Reason Codes

When a tokenization rule's conditions are met, one of two actions is taken:

DECLINE

Reject the tokenization request outright. The cardholder will not be able to add the card to the wallet or merchant.

Optional reason codes for tracking and observability:

REQUIRE_TFA

Require the cardholder to complete two-factor authentication before the tokenization can proceed. The cardholder will be prompted to verify their identity via SMS, email, or in-app authentication.

📘

If your rules use the REQUIRE_TFA action, you must also configure 2FA for Tokenization.

Optional reason codes for tracking and observability:

See the API spec for the full list of reason codes.

Creating a Tokenization Rule

Tokenization rules can be created via the API or through the Lithic Dashboard UI. To create a rule via the API, use the POST /v2/auth_rules endpoint with the event_stream set to TOKENIZATION and the type set to CONDITIONAL_ACTION.

Like all authorization rules, tokenization rules can be scoped to:

• Program level: Set program_level: true to apply across the entire card program. Optionally use excluded_card_tokens, excluded_account_tokens, or excluded_business_account_tokens to exempt specific entities.
• Account level: Provide account_tokens and/or business_account_tokens to apply to specific accounts
• Card level: Provide card_tokens to target specific cards

Example: Require TFA for high-risk wallet scores

This rule requires two-factor authentication when the wallet provider's account risk score indicates elevated risk:

{
  "name": "TFA for high-risk wallet accounts",
  "program_level": true,
  "type": "CONDITIONAL_ACTION",
  "event_stream": "TOKENIZATION",
  "parameters": {
    "action": {
      "type": "REQUIRE_TFA",
      "reason": "ACCOUNT_SCORE_LOW"
    },
    "conditions": [
      {
        "attribute": "WALLET_ACCOUNT_SCORE",
        "operation": "IS_LESS_THAN",
        "value": 3
      }
    ]
  }
}

Testing and Deploying Rules

Tokenization rules follow the same draft, shadow, and promote lifecycle as all Authorization Rules.

Shadow Mode

When you create a tokenization rule, it starts in shadow mode. In shadow mode, the rule evaluates live tokenization requests and logs what action it would have taken, but does not affect actual outcomes. This lets you measure impact before going live.

Review rule performance using the performance reports feature, or query the rule results endpoint to see individual evaluations.

Promoting a Rule

Once you are satisfied with a rule's shadow mode performance, promote it to active using the promote endpoint. The rule will immediately begin affecting tokenization outcomes.

Monitoring Rule Results

When a tokenization is processed, the evaluation results for each rule are available in multiple places:

• Tokenization events: The rule_results array on each tokenization event includes the auth_rule_token, result (APPROVED, DECLINED, REQUIRE_TFA, or ERROR), name, and explanation for each rule that was evaluated. Events also include aggregated tokenization_decline_reasons and tokenization_tfa_reasons.
• Tokenization webhooks: The tokenization.approval_request and digital_wallet.tokenization_approval_request webhooks include rule_results, tokenization_decline_reasons, and tokenization_tfa_reasons.
• Rule results endpoint: Use the rule results endpoint to query evaluation results. At least one filter (event_token or auth_rule_token) must be provided.

Limitations

• Rule types: The TOKENIZATION event stream supports CONDITIONAL_ACTION and TYPESCRIPT_CODE rule types. Velocity limits are not available for tokenization rules.
• Wallet precedence: Your rules cannot override a wallet provider's decline recommendation. Rules can only make decisions more restrictive, not more permissive.
• Merchant tokenizations: Client-configured tokenization rules do not apply to merchant tokenizations. Only Lithic Tokenization Decisioning is evaluated for merchant tokenization requests.
• TFA eligibility: If a rule returns REQUIRE_TFA but the card or program is not configured to support TFA, the decision is converted to DECLINE. Ensure 2FA for Tokenization is configured before using REQUIRE_TFA actions.
• Error handling: If a rule evaluation encounters an error, the tokenization request is declined. The system fails closed for safety.
• Backtesting: Backtesting is not currently supported for tokenization rules. Use shadow mode and performance reports to evaluate rule impact before promoting.

Next Steps

• Authorization Rules: Learn about the full Authorization Rules framework, including velocity limits and conditional actions for card transactions
• Customer Tokenization Decisioning: Set up a custom responder for fully custom tokenization logic
• 2FA for Tokenization: Configure two-factor authentication for tokenization flows
• About Digital Wallets: Overview of how digital wallet tokenization works at Lithic