Lithic API Documentation | Auth Rules › V2 › Calculated Feature Values

Auth Rules

auth_rules

Auth Rules

V2

auth_rules.v2

Methods

Create A New Rule ->

AuthRule

post/v2/auth_rules

Creates a new V2 Auth rule in draft mode

List Rules -> CursorPage<

AuthRule

get/v2/auth_rules

Lists V2 Auth rules

Fetch A Rule ->

AuthRule

get/v2/auth_rules/{auth_rule_token}

Fetches a V2 Auth rule by its token

path Parameters

auth_rule_token: string

(format: uuid)

Response fields

AuthRule

Request example

curl https://api.lithic.com/v2/auth_rules/$AUTH_RULE_TOKEN \
    -H "Authorization: $LITHIC_API_KEY"

200Example

{
  "token": "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
  "account_tokens": [
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
  ],
  "business_account_tokens": [
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
  ],
  "card_tokens": [
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
  ],
  "current_version": {
    "parameters": {
      "conditions": [
        {
          "attribute": "MCC",
          "operation": "IS_ONE_OF",
          "value": "string"
        }
      ]
    },
    "version": 0
  },
  "draft_version": {
    "parameters": {
      "conditions": [
        {
          "attribute": "MCC",
          "operation": "IS_ONE_OF",
          "value": "string"
        }
      ]
    },
    "version": 0
  },
  "event_stream": "AUTHORIZATION",
  "lithic_managed": true,
  "name": "name",
  "program_level": true,
  "state": "ACTIVE",
  "type": "CONDITIONAL_BLOCK",
  "excluded_card_tokens": [
    "182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e"
  ]
}

Update A Rule ->

AuthRule

patch/v2/auth_rules/{auth_rule_token}

Updates a V2 Auth rule's properties

If account_tokens, card_tokens, program_level, or excluded_card_tokens is provided, this will replace existing associations with the provided list of entities.

Delete A Rule ->

delete/v2/auth_rules/{auth_rule_token}

Deletes a V2 Auth rule

Draft A New Rule Version ->

AuthRule

post/v2/auth_rules/{auth_rule_token}/draft

Creates a new draft version of a rule that will be ran in shadow mode.

This can also be utilized to reset the draft parameters, causing a draft version to no longer be ran in shadow mode.

Promote A Rule Version ->

AuthRule

post/v2/auth_rules/{auth_rule_token}/promote

Promotes the draft version of an Auth rule to the currently active version such that it is enforced in the respective stream.

Retrieve A Performance Report -> { auth_rule_token, begin, daily_statistics, 1 more... }

get/v2/auth_rules/{auth_rule_token}/report

Retrieves a performance report for an Auth rule containing daily statistics and evaluation outcomes.

Time Range Limitations:

Reports are supported for the past 3 months only
Maximum interval length is 1 month
Report data is available only through the previous day in UTC (current day data is not available)

The report provides daily statistics for both current and draft versions of the Auth rule, including approval, decline, and challenge counts along with sample events.

Calculated Feature Values -> { evaluated, features }

get/v2/auth_rules/{auth_rule_token}/features

Fetches the current calculated Feature values for the given Auth Rule

This only calculates the features for the active version.

VelocityLimit Rules calculates the current Velocity Feature data. This requires a card_token or account_token matching what the rule is Scoped to.
ConditionalBlock Rules calculates the CARD_TRANSACTION_COUNT_* attributes on the rule. This requires a card_token

path Parameters

auth_rule_token: string

(format: uuid)

query Parameters

account_token: string

Optional

(format: uuid)

card_token: string

Optional

(format: uuid)

Response fields

evaluated: string

(format: date-time)

Timestamp at which the Features were evaluated

features: Array<{ filters, period, scope, 1 more... }>

Calculated Features used for evaluation of the provided Auth Rule

Request example

curl https://api.lithic.com/v2/auth_rules/$AUTH_RULE_TOKEN/features \
    -H "Authorization: $LITHIC_API_KEY"

200Example

{
  "evaluated": "2019-12-27T18:11:19.117Z",
  "features": [
    {
      "filters": {
        "exclude_countries": [
          "USD"
        ],
        "exclude_mccs": [
          "5542"
        ],
        "include_countries": [
          "USD"
        ],
        "include_mccs": [
          "5542"
        ],
        "include_pan_entry_modes": [
          "AUTO_ENTRY"
        ]
      },
      "period": {
        "duration": 10,
        "type": "CUSTOM"
      },
      "scope": "CARD",
      "value": {
        "amount": 0,
        "count": 0
      }
    }
  ]
}

Domain types

AuthRule = { token, account_tokens, business_account_tokens, 10 more... }

AuthRuleCondition = { attribute, operation, value }

Conditional3DSActionParameters = { action, conditions }

ConditionalACHActionParameters = { action, conditions }

ConditionalAttribute = "MCC" | "COUNTRY" | "CURRENCY" | 14 more...

The attribute to target.

The following attributes may be targeted:

MCC: A four-digit number listed in ISO 18245. An MCC is used to classify a business by the types of goods or services it provides.
COUNTRY: Country of entity of card acceptor. Possible values are: (1) all ISO 3166-1 alpha-3 country codes, (2) QZZ for Kosovo, and (3) ANT for Netherlands Antilles.
CURRENCY: 3-character alphabetic ISO 4217 code for the merchant currency of the transaction.
MERCHANT_ID: Unique alphanumeric identifier for the payment card acceptor (merchant).
DESCRIPTOR: Short description of card acceptor.
LIABILITY_SHIFT: Indicates whether chargeback liability shift to the issuer applies to the transaction. Valid values are NONE, 3DS_AUTHENTICATED, or TOKEN_AUTHENTICATED.
PAN_ENTRY_MODE: The method by which the cardholder's primary account number (PAN) was entered. Valid values are AUTO_ENTRY, BAR_CODE, CONTACTLESS, ECOMMERCE, ERROR_KEYED, ERROR_MAGNETIC_STRIPE, ICC, KEY_ENTERED, MAGNETIC_STRIPE, MANUAL, OCR, SECURE_CARDLESS, UNSPECIFIED, UNKNOWN, CREDENTIAL_ON_FILE, or ECOMMERCE.
TRANSACTION_AMOUNT: The base transaction amount (in cents) plus the acquirer fee field in the settlement/cardholder billing currency. This is the amount the issuer should authorize against unless the issuer is paying the acquirer fee on behalf of the cardholder.
RISK_SCORE: Network-provided score assessing risk level associated with a given authorization. Scores are on a range of 0-999, with 0 representing the lowest risk and 999 representing the highest risk. For Visa transactions, where the raw score has a range of 0-99, Lithic will normalize the score by multiplying the raw score by 10x.
CARD_TRANSACTION_COUNT_15M: The number of transactions on the card in the trailing 15 minutes before the authorization.
CARD_TRANSACTION_COUNT_1H: The number of transactions on the card in the trailing hour up and until the authorization.
CARD_TRANSACTION_COUNT_24H: The number of transactions on the card in the trailing 24 hours up and until the authorization.
CARD_STATE: The current state of the card associated with the transaction. Valid values are CLOSED, OPEN, PAUSED, PENDING_ACTIVATION, PENDING_FULFILLMENT.
PIN_ENTERED: Indicates whether a PIN was entered during the transaction. Valid values are TRUE, FALSE.
PIN_STATUS: The current state of card's PIN. Valid values are NOT_SET, OK, BLOCKED.
WALLET_TYPE: For transactions using a digital wallet token, indicates the source of the token. Valid values are APPLE_PAY, GOOGLE_PAY, SAMSUNG_PAY, MASTERPASS, MERCHANT, OTHER, NONE.
ADDRESS_MATCH: Lithic's evaluation result comparing transaction's address data with the cardholder KYC data if it exists. Valid values are MATCH, MATCH_ADDRESS_ONLY, MATCH_ZIP_ONLY,MISMATCH,NOT_PRESENT.

ConditionalAuthorizationActionParameters = { action, conditions }

ConditionalBlockParameters = { conditions }

ConditionalOperation = "IS_ONE_OF" | "IS_NOT_ONE_OF" | "MATCHES" | 12 more...

The operation to apply to the attribute

ConditionalTokenizationActionParameters = { action, conditions }

ConditionalValue = string | number | Array<string> | 1 more...

A regex string, to be used with MATCHES or DOES_NOT_MATCH

EventStream = "AUTHORIZATION" | "THREE_DS_AUTHENTICATION" | "TOKENIZATION" | 2 more...

The event stream during which the rule will be evaluated.

MerchantLockParameters = { merchants }

RuleStats = { approved, challenged, declined, 2 more... }

VelocityLimitParams = { filters, period, scope, 2 more... }

VelocityLimitPeriod = { duration, type } | { type } | { type, day_of_week } | 2 more...

Velocity over the current day since 00:00 / 12 AM in Eastern Time

Auth Rules V2

Backtests

auth_rules.v2.backtests

Methods

Request A Backtest -> { backtest_token }

post/v2/auth_rules/{auth_rule_token}/backtests

Initiates a request to asynchronously generate a backtest for an Auth rule. During backtesting, both the active version (if one exists) and the draft version of the Auth Rule are evaluated by replaying historical transaction data against the rule's conditions. This process allows customers to simulate and understand the effects of proposed rule changes before deployment. The generated backtest report provides detailed results showing whether the draft version of the Auth Rule would have approved or declined historical transactions which were processed during the backtest period. These reports help evaluate how changes to rule configurations might affect overall transaction approval rates.

The generated backtest report will be delivered asynchronously through a webhook with event_type = auth_rules.backtest_report.created. See the docs on setting up webhook subscriptions. It is also possible to request backtest reports on-demand through the /v2/auth_rules/{auth_rule_token}/backtests/{auth_rule_backtest_token} endpoint.

Lithic currently supports backtesting for CONDITIONAL_BLOCK / CONDITIONAL_ACTION rules. Backtesting for VELOCITY_LIMIT rules is generally not supported. In specific cases (i.e. where Lithic has pre-calculated the requested velocity metrics for historical transactions), a backtest may be feasible. However, such cases are uncommon and customers should not anticipate support for velocity backtests under most configurations. If a historical transaction does not feature the required inputs to evaluate the rule, then it will not be included in the final backtest report.

Retrieve Backtest Results ->

BacktestResults

get/v2/auth_rules/{auth_rule_token}/backtests/{auth_rule_backtest_token}

Returns the backtest results of an Auth rule (if available).

Backtesting is an asynchronous process that requires time to complete. If a customer retrieves the backtest results using this endpoint before the report is fully generated, the response will return null for results.current_version and results.draft_version. Customers are advised to wait for the backtest creation process to complete (as indicated by the webhook event auth_rules.backtest_report.created) before retrieving results from this endpoint.

Backtesting is an asynchronous process, while the backtest is being processed, results will not be available which will cause results.current_version and results.draft_version objects to contain null. The entries in results will also always represent the configuration of the rule at the time requests are made to this endpoint. For example, the results for current_version in the served backtest report will be consistent with which version of the rule is currently activated in the respective event stream, regardless of which version of the rule was active in the event stream at the time a backtest is requested.

Domain types

BacktestResults = { backtest_token, results, simulation_parameters }