Overview

A hold adjustment rule changes the authorization hold placed on a transaction when it matches a set of conditions you define. It uses the CONDITIONAL_ACTION rule type on the AUTHORIZATION event stream, the same type as Conditional Action Rules, but instead of an action such as DECLINE or CHALLENGE, its action is a HOLD_ADJUSTMENT that changes the amount reserved against the cardholder's available balance.

The initial authorization amount often does not reflect the final clearing amount:

• A restaurant or bar adds a tip after the card is presented, so the transaction clears for more than the amount authorized
• An automated fuel dispenser validates the card with a nominal authorization (often $1.00) but allows a full tank to be pumped

In each case the amount ultimately debited from the cardholder's balance can exceed the authorization amount, which can drive the balance negative. A hold adjustment rule reserves enough balance up front to cover the expected final amount. It does not decline or cap the transaction the way a conditional action or velocity limit rule does; it only changes the balance reserved for it.

Choosing an Adjustment Value

The right adjustment depends on your card program and the networks on which it runs. For categories where the final amount commonly exceeds the authorization amount, such as tipping and automated fuel dispensers, networks typically define the maximum a transaction may clear above the authorization amount without an additional authorization. Above that tolerance, the issuer has a chargeback right for the excess. Refer to the card network guidance for your program, and size the adjustment to stay within that tolerance.

As an example, at the time of writing, Visa's US consumer construct allows the following clearing tolerances above the authorization amount:

As an example, at the time of writing, Mastercard's US consumer construct allows the following clearing tolerances above the authorization amount:

How It Works

A hold adjustment rule is evaluated like a conditional action rule:

1. The rule's conditions are checked against the incoming authorization
2. If every condition matches, the configured adjustment computes a new hold amount
3. Lithic checks the adjusted hold against the cardholder's available balance, then places the hold

Only the hold changes. The cardholder and merchant amounts continue to reflect the original authorization amount. When the transaction clears, or when an authorization advice arrives with the actual amount (for example, a fuel pump reporting the amount dispensed), the hold is adjusted to the actual amount and any excess is released.

When several hold adjustment rules match the same transaction, the highest resulting hold amount applies.

Parameters

A hold adjustment rule is created with two parameters: a set of conditions and an action.

Conditions

Conditions use the same structure as conditional action rules. Each condition is an attribute, an operation, and a value, and a transaction must match every condition in the rule for the adjustment to apply. For the full set of attributes (such as MCC, COUNTRY, and TRANSACTION_AMOUNT) and operations, see Conditional Action Rules. Fraud Command customers can also target cross-border transactions with IS_DOMESTIC. See Non-Domestic Transactions.

Action

A hold adjustment rule specifies its hold change in the action parameter, the same parameter a conditional action rule uses for a DECLINE or CHALLENGE. For a hold adjustment, action is an object:

• type: the action type. HOLD_ADJUSTMENT is currently the only supported value
• mode: how value is interpreted
• value: an integer, interpreted according to mode

Use a positive value to increase the hold; for ADD_PERCENTAGE, a value of 0 leaves the hold unchanged. ADD_PERCENTAGE and ADD_AMOUNT raise the reserved balance relative to the original authorization amount, while REPLACE_WITH_AMOUNT sets the hold to the configured amount regardless of the original authorization amount, so choose a value high enough to cover the expected clearing amount. Percentage adjustments are rounded up to the nearest cent so the hold fully covers the expected amount.

Examples

Hold adjustment rules are scoped like other Authorization Rules, with the entities parameter (see Scoping a Rule). The two requests below each create a program-level rule:

1. Tip buffer: adds a 30% buffer to the hold on restaurant transactions (MCC 5812) to cover a post-authorization tip
2. Fuel dispenser: replaces the hold with a fixed $175.00 on $1.00 automated fuel dispenser authorizations in the US (MCC 5542)

{
  "name": "Restaurant tip hold buffer",
  "entities": {
    "include": [{ "type": "PROGRAM" }]
  },
  "type": "CONDITIONAL_ACTION",
  "event_stream": "AUTHORIZATION",
  "parameters": {
    "conditions": [
      {
        "attribute": "MCC",
        "operation": "IS_ONE_OF",
        "value": ["5812"]
      }
    ],
    "action": {
      "type": "HOLD_ADJUSTMENT",
      "mode": "ADD_PERCENTAGE",
      "value": 3000
    }
  }
}

{
  "name": "AFD fixed hold",
  "entities": {
    "include": [{ "type": "PROGRAM" }]
  },
  "type": "CONDITIONAL_ACTION",
  "event_stream": "AUTHORIZATION",
  "parameters": {
    "conditions": [
      {
        "attribute": "MCC",
        "operation": "IS_ONE_OF",
        "value": ["5542"]
      },
      {
        "attribute": "COUNTRY",
        "operation": "IS_ONE_OF",
        "value": ["USA"]
      },
      {
        "attribute": "TRANSACTION_AMOUNT",
        "operation": "IS_EQUAL_TO",
        "value": 100
      }
    ],
    "action": {
      "type": "HOLD_ADJUSTMENT",
      "mode": "REPLACE_WITH_AMOUNT",
      "value": 17500
    }
  }
}

Each request creates a draft rule that runs in shadow mode and does not change live holds until you promote it. See Authorization Rule Lifecycle for the full draft, promote, and disable flow.

Non-Domestic Transactions

The IS_DOMESTIC attribute compares the merchant's country against the issuing country of the card's program. Use it to reserve extra balance on cross-border transactions.

IS_DOMESTIC is a boolean attribute. Use IS_ONE_OF or IS_NOT_ONE_OF with ["TRUE"] or ["FALSE"].

The following request adds a 3% buffer to the hold on non-domestic transactions:

{
  "name": "Non-domestic hold buffer",
  "entities": {
    "include": [{ "type": "PROGRAM" }]
  },
  "type": "CONDITIONAL_ACTION",
  "event_stream": "AUTHORIZATION",
  "parameters": {
    "conditions": [
      {
        "attribute": "IS_DOMESTIC",
        "operation": "IS_ONE_OF",
        "value": ["FALSE"]
      }
    ],
    "action": {
      "type": "HOLD_ADJUSTMENT",
      "mode": "ADD_PERCENTAGE",
      "value": 300
    }
  }
}

Each card is compared against the issuing country of its own card program. For card programs that issue in more than one country, one program-level rule applies the correct comparison to every card.

If a card's program has no issuing country configured, the condition does not match and the rule does not adjust the hold.

Observing the Adjusted Hold

After a hold adjustment rule applies, the adjusted amount appears in the transaction's amounts.hold, while amounts.cardholder and amounts.merchant continue to show the original authorization amount. For a restaurant authorization of $50.00 with a 30% buffer, the hold is $65.00:

"amounts": {
  "cardholder": {
    "amount": -5000,
    "conversion_rate": "1.000000",
    "currency": "USD"
  },
  "hold": {
    "amount": -6500,
    "currency": "USD"
  },
  "merchant": {
    "amount": -5000,
    "currency": "USD"
  },
  "settlement": {
    "amount": 0,
    "currency": "USD"
  }
}

As the transaction clears, or as authorization advices arrive with the actual amount, the hold is adjusted to the cleared amount and any excess is released. The adjusted hold is also reflected in the amounts.hold of Auth Stream Access (ASA) requests, so ASA endpoints see the padded hold while the cardholder amount stays at the original authorization amount.

Rule results record which rules applied to a transaction, so you can confirm that a hold adjustment took effect and measure its impact before and after promoting. See Analytics and Observability.

Interactions and Limitations

• Balance checks and declines: the adjusted hold, not the original authorization amount, is checked against the cardholder's available balance, so a transaction is approved only if the available balance covers the adjusted hold
• Effect on other rules: a hold adjustment changes only the balance reserved for the transaction, not the amount that other rules evaluate. A conditional action rule testing TRANSACTION_AMOUNT or CASH_AMOUNT, and a velocity limit rule counting spend, always use the original authorization amount, not the adjusted hold. For example, a 30% hold adjustment on a $50.00 authorization does not cause a conditional action rule that declines above $60.00, or a velocity limit, to evaluate the transaction as $65.00; both still use $50.00
• Partial approval: where the terminal supports partial approval (common at automated fuel dispensers), a transaction whose adjusted hold exceeds the available balance can be partially approved up to the available balance instead of declined. This is network and terminal behavior and does not require an Auth Stream Access (ASA) integration
• Hold duration: a padded hold follows the same lifecycle as any authorization hold. It is reduced as the transaction clears or as authorization advices arrive, and an uncleared hold is released on the standard authorization expiry schedule. See Expiring Authorizations
• Multiple matching rules: when more than one hold adjustment rule matches a transaction, including rules applied through different entities (program, account, business account, card, or card tag), the highest resulting hold amount applies across all of them. A hold adjustment does not prevent another rule from declining or challenging the same transaction
• Event stream: hold adjustments apply only on the AUTHORIZATION event stream
• Single-message transactions: hold adjustments apply only to dual-message authorizations. A single-message financial transaction, such as many PIN debit purchases, posts immediately and is not adjusted

Next Steps

• Conditional Action Rules: the attributes, operations, and conditions a hold adjustment rule reuses
• Authorization Rule Lifecycle: draft, test in shadow mode, promote, and disable rules
• Velocity Limit Rules: restrict transaction count or spend over time
• Analytics and Observability: measure rule impact and interpret rule results