📘

Authorization Challenges is a premium feature included in Lithic Fraud Command. Read more about Fraud Command here.

Introduction

Authorization Challenges provide a step-up authentication mechanism for verifying cardholder identity during high-risk transactions. When authorization logic identifies a transaction as potentially fraudulent, Lithic declines the authorization and prompts the cardholder to confirm the purchase. Upon successful validation, the cardholder can reattempt the transaction.

Challenges are delivered to the cardholder according to the program's configured orchestration model:

• Lithic Orchestration: Lithic delivers and verifies an SMS prompt end to end.
• Customer Orchestration: Lithic emits a webhook to the program at the moment a challenge is issued, and the program delivers the prompt through its own channel (mobile push notification, WhatsApp, in-app prompt, biometric verification, etc.) before posting the cardholder's response back to Lithic.

Lithic Orchestration is the fastest path to a working challenge flow for programs with US-centric cardholders and no existing in-house authentication infrastructure. Customer Orchestration is the natural fit for programs with international cardholders, programs that already authenticate cardholders through a mobile app, or programs that want challenges to feel native to their existing brand experience.

How Authorization Challenges Work

When Authorization Rules or ASA logic trigger a challenge, Lithic declines the authorization immediately and dispatches the challenge to the cardholder through the orchestration model configured for the program. Cardholders have up to 10 minutes to respond before the challenge expires. The flow is asynchronous by design, since authorization responses must be delivered within network timeout windows: the cardholder responds to the challenge first, then retries the transaction.

Cardholder response to the challenge determines how Lithic handles retry attempts, though the specific behavior differs between Authorization Rules and ASA implementations. When the cardholder retries the transaction after a successful validation, Authorization Rules will bypass the challenge requirement automatically, while ASA implementations receive challenge state information in the latest_challenge object and decide independently.

Challenge Orchestration Models

The orchestration model determines how challenges are delivered to the cardholder. It is configured at the program level, regardless of whether the challenge originates from an Authorization Rule or from Authorization Stream Access.

Lithic Orchestration

Lithic manages the complete challenge delivery and verification process. When a challenge is triggered, Lithic sends a templated SMS to the cardholder's phone number, collects the YES/NO response, and records the outcome. The program's responsibility is to keep cardholder phone numbers current in Lithic (for Rules-triggered challenges) or to include a phone number in the ASA response (for ASA-triggered challenges).

This model is appropriate for programs whose cardholders are concentrated in regions where SMS delivery is reliable and where a standard SMS challenge experience meets the program's needs.

Customer Orchestration

The card program controls challenge delivery and response collection. When a challenge is triggered, Lithic emits a card_authorization.challenge webhook to the program with the authorization context and the challenge token. The program delivers the prompt through its own channel and submits the cardholder's response back to Lithic via the challenge response endpoint.

This model is appropriate for programs that want full control over the cardholder experience, need to support cardholders through channels other than SMS, or already operate their own authentication infrastructure such as a mobile app login flow. Programs that have integrated Lithic's 3DS Customer Orchestration flow will find a similar webhook + response pattern here, scoped to authorization challenges rather than 3DS authentication.

The orchestration model is configured at the program level and applies to every challenge for the program. There is no per-card or per-rule override, and Lithic does not automatically fall back to SMS if the program's endpoint is unavailable.

Triggering Authorization Challenges

Authorization Challenges can be initiated through two distinct mechanisms: Authorization Rules or Authorization Stream Access.

Using Authorization Rules

Authorization Rules enable challenge triggering through the CONDITIONAL_ACTION rule type with the action parameter set to CHALLENGE. Rules evaluate transaction attributes and initiate challenges when all specified conditions are satisfied.

Example request to create a challenge rule:

POST /v2/auth_rules

{
  "program_level": true,
  "type": "CONDITIONAL_ACTION",
  "event_stream": "AUTHORIZATION",
  "parameters": {
    "action": "CHALLENGE",
    "conditions": [
      {
        "attribute": "TRANSACTION_AMOUNT",
        "operation": "IS_GREATER_THAN",
        "value": 50000
      },
      {
        "attribute": "RISK_SCORE",
        "operation": "IS_GREATER_THAN",
        "value": 700
      }
    ]
  }
}

This configuration challenges transactions exceeding $500 with network risk scores above 700. Consult the Auth Rules API specification for the complete attribute catalog and supported operations.

Authorization challenges can also be configured via the Rules tab within the Lithic Dashboard.

Under Lithic Orchestration, Authorization Rules use the phone number associated with the card's accountholder. If the phone number was not provided during accountholder creation or has changed, the number must be updated with Lithic for challenges to be delivered correctly. When no phone number is associated with the accountholder, transactions will be declined and no SMS will be sent. Under Customer Orchestration, no phone number is required, as the program delivers the challenge through its own channel.

Authorization Rules are appropriate when challenge criteria can be expressed through transaction attributes accessible within Lithic's authorization context. This approach requires no external infrastructure. However, rules cannot incorporate external data sources or implement complex decisioning logic requiring contextual information beyond the transaction object. If this is required, authorization challenges can also be implemented via Authorization Stream Access.

Using Authorization Stream Access

Authorization Stream Access provides programmatic challenge control through a customer decisioning endpoint. Responding with CHALLENGE in the ASA response initiates the challenge flow.

Example ASA response triggering a challenge:

{
  "result": "CHALLENGE"
}

Under Lithic Orchestration, the ASA response can optionally include a phone number for SMS delivery. If provided, Lithic uses that number; if omitted, Lithic uses the accountholder's phone number on file. When no phone number is available through either method, the transaction is declined and no SMS is sent.

Example ASA response with phone number:

{
  "result": "CHALLENGE",
  "challenge_phone_number": "+15551234567"
}

Refer to the ASA request specification for complete request format documentation.

Providing the phone number in the ASA response enables challenge initiation even when no phone number is associated with the accountholder in Lithic's system, offering greater flexibility for phone number management. Under Customer Orchestration, the challenge_phone_number parameter is ignored, as the program delivers the challenge through its own channel.

Out of Band Challenge Flow

When a program is configured for Customer Orchestration, Lithic notifies the program at the moment a challenge is issued. The same card_authorization.challenge webhook fires whether the challenge originated from an Authorization Rule or from an ASA response. The program is then responsible for delivering the challenge to the cardholder through its own channel, collecting either an APPROVE or DECLINE response, and submitting it back to Lithic before the challenge expires.

sequenceDiagram
    participant C as Cardholder
    participant M as Merchant
    participant N as Network
    participant L as Lithic
    participant P as Card Program

    C->>M: Initiates<br/>transaction
    M->>N: Authorization<br/>request
    N->>L: Authorization<br/>request

    Note over L: Rule or ASA<br/>triggers challenge

    L-->>N: DECLINED<br/>(CARDHOLDER_CHALLENGED)
    N-->>M: DECLINED
    M-->>C: Transaction<br/>declined

    L->>P: card_authorization.challenge<br/>webhook (event_token, authorization details)
    P->>C: Deliver challenge<br/>(push, WhatsApp, in-app, etc.)
    C-->>P: Cardholder response
    P->>L: POST /v1/card_authorizations/<br/>{event_token}/challenge_response

    Note over C,M: Cardholder retries transaction

    C->>M: Retry
    M->>N: Authorization request
    N->>L: Authorization request
    Note over L: Bypass applies (Rules)<br/>or challenge state surfaced<br/>via ASA latest_challenge
    L-->>N: APPROVED
    N-->>M: APPROVED
    M-->>C: Approved

Challenge Webhook

When a challenge is triggered, Lithic sends a card_authorization.challenge webhook to the program. The payload includes the authorization that triggered the challenge and challenge-specific details: the event_token used to respond, plus the issue and expiration timestamps.

Webhook delivery is signed and authenticated using the same scheme as all other Lithic events. See Verifying Webhooks for the recommended HMAC validation approach and supported headers before processing any payload.

Example webhook payload (truncated for readability):

{
  "event_type": "card_authorization.challenge",
  "authorization": {
    "token": "a4e8dc9a-f821-4365-b6a9-a6219b105b6d",
    "event_token": "bbbf1e86-322d-11ee-9779-00505685a123",
    "merchant": {
      "descriptor": "BOBS HARDWARE STORE",
      "mcc": "5251",
      "city": "NEW YORK",
      "state": "NY",
      "country": "USA"
    },
    "amounts": {
      "cardholder": {
        "amount": 7550,
        "currency": "USD",
        "conversion_rate": "1"
      },
      "merchant": {
        "amount": 7550,
        "currency": "USD"
      },
      "settlement": null,
      "hold": {
        "amount": 7550,
        "currency": "USD"
      }
    },
    "card": {
      "token": "f2c7d5e1-9b3a-4c82-8e61-7d94a1c2b5f0",
      "last_four": "1234",
      "memo": "Employee Travel Card",
      "state": "OPEN",
      "type": "VIRTUAL"
    }
  },
  "challenge": {
    "event_token": "bbbf1e86-322d-11ee-9779-00505685a123",
    "start_time": "2026-05-15T14:23:45Z",
    "expiry_time": "2026-05-15T14:33:45Z"
  }
}

The authorization object contains the same payload shape used in ASA requests, including merchant details, amounts, card identifiers, and POS context. This gives the program everything it needs to compose a meaningful prompt for the cardholder, for example by including the merchant name and transaction amount in the challenge message. The example above omits parameters that are not directly relevant for composing a challenge prompt; refer to the ASA request specification for the complete authorization payload structure.

To subscribe to this event, configure a webhook endpoint that listens for card_authorization.challenge. See Types of Events for general webhook configuration guidance.

Responding to a Challenge

After collecting the cardholder's response, the program submits the result to Lithic using the challenge response endpoint:

POST /v1/card_authorizations/{event_token}/challenge_response

The event_token path parameter is the challenge.event_token value delivered in the webhook (which corresponds to the authorization event that was challenged, not the parent transaction token). The request body must include a response parameter set to either APPROVE or DECLINE.

Example request:

curl --request POST \
  --url 'https://api.lithic.com/v1/card_authorizations/bbbf1e86-322d-11ee-9779-00505685a123/challenge_response' \
  --header 'Authorization: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "response": "APPROVE"
  }'

The endpoint returns:

Refer to Respond to Authorization Challenge for the complete endpoint specification.

Response Window

The cardholder must respond within 10 minutes of the challenge being issued. The exact expiration is included in the webhook as challenge.expiry_time. Responses submitted after this window receive a 410 and are not honored; allow a small safety margin when scheduling the POST. If no response is received before expiration, the challenge is recorded as expired and the cardholder will be challenged again on the next qualifying transaction.

The program is responsible for instructing the cardholder to retry the transaction at the merchant after approving the challenge. Lithic does not re-present the authorization on its own; the cardholder must initiate a new attempt for the bypass (Rules) or latest_challenge state (ASA) to take effect.

If a network or timeout error occurs while posting the response, the program may safely retry the same request. Once a response has been recorded, subsequent POSTs to the same event_token return 409 and do not alter the recorded outcome.

Authorization Behavior for Completed Challenge

Challenge behavior differs fundamentally between Authorization Rules and Authorization Stream Access implementations. The behaviors described below apply equally to challenges delivered via Lithic Orchestration and Customer Orchestration.

Authorization Rules Behavior for Completed Challenges

When challenges are triggered via Authorization Rules, Lithic automatically applies logic which bypasses additional challenges after a successful challenge completion. The cardholder must respond within 10 minutes of the challenge being issued; if no response is received within this window, the challenge expires and no bypass record is created. Upon receiving a "YES" response from the cardholder, the system creates a bypass record scoped to the card and merchant combination. This bypass prevents the specific challenge rule from triggering again for 24 hours for the same card at the same merchant ID.

The bypass applies exclusively to the challenge requirement. All other authorization rules continue to evaluate normally. If a cardholder successfully completes a challenge at Merchant A, later transactions on the same card at Merchant A within the bypass window will not trigger the same Authorization Challenge rule. However, those transactions remain subject to all other authorization rules including spend limits, velocity limits, merchant locks, and any other configured rules. Transactions at Merchant B remain subject to challenge evaluation, as bypass records are merchant-specific.

Authorization Stream Access Bypass Behavior

ASA implementations receive challenge state information but must implement bypass logic within their own decisioning endpoint. Lithic does not automatically approve authorizations based on challenge completion. The program's ASA endpoint receives every authorization request regardless of challenge state and must return an authorization decision for each authorization request.

ASA requests include a latest_challenge object when a recent challenge exists for the card and merchant combination.

Example latest_challenge object:

{
  "status": "COMPLETED",
  "phone_number": "+15551234567",
  "completed_at": "2024-10-09T14:23:45Z"
}

The status parameter indicates challenge state:

• COMPLETED: Cardholder successfully approved the challenge
• DECLINED: Cardholder declined the challenge (terminal state; subsequent retries will be re-challenged or remain declined per the program's rules)
• PENDING: Challenge remains open awaiting cardholder response
• EXPIRED: Challenge timeout occurred without completion
• ERROR: Challenge processing encountered a system error

The phone_number parameter contains the phone number used for SMS delivery under Lithic Orchestration; it is not meaningful for Customer-Orchestrated challenges, which are not delivered via SMS. The completed_at parameter appears only when status is COMPLETED; it is not set for DECLINED, EXPIRED, or ERROR outcomes.

The program's ASA decisioning logic must evaluate this object and determine whether to approve, decline, or re-challenge based on challenge state and risk tolerance. For example, if status is COMPLETED and the completed_at timestamp is recent, the decisioning logic may return APPROVED rather than CHALLENGE.

Lithic will honor the decision returned by the endpoint precisely. Lithic does not enforce any default bypass behavior for ASA-triggered challenges.

Receiving Challenge Response Events

📘

The card_authorization.challenge_response event applies to Lithic Orchestration only. Under Customer Orchestration, the program already has the cardholder's response from its own delivery channel.

Programs can subscribe to the card_authorization.challenge_response event to receive a webhook each time a cardholder responds to an SMS challenge. The event delivers the cardholder's response, APPROVE or DECLINE, along with the associated transaction and card tokens, enabling programs to take automated action such as suspending a card after a decline.

Example event payload:

{
  "event_type": "card_authorization.challenge_response",
  "event_token": "bbbf1e86-322d-11ee-9779-00505685a123",
  "transaction_token": "a4e8dc9a-f821-4365-b6a9-a6219b105b6d",
  "card_token": "f2c7d5e1-9b3a-4c82-8e61-7d94a1c2b5f0",
  "challenge_method": "SMS",
  "response": "APPROVE",
  "created": "2026-04-16T14:23:45Z",
  "completed": "2026-04-16T14:24:31Z"
}

Refer to Types of Events for the full list of subscribable events and details on configuring webhook endpoints.

Customizing Challenge Messages

📘

Message customization applies to Lithic Orchestration only. Under Customer Orchestration, the program controls the wording and presentation of the challenge prompt in its own channel.

Under Lithic Orchestration, the authorization challenge flow consists of three SMS messages that card programs can fully customize: the initial challenge request, the affirmative response followup, and the negative response followup. A negative response also instructs the cardholder to pause the card and contact their card issuer.

The initial message requests cardholder confirmation about the transaction attempt. This message should provide sufficient transaction context for the cardholder to recognize whether they initiated the purchase and clearly indicate that a YES or NO response is required. For example:

Did you attempt a $75.50 transaction at BOBS HARDWARE STORE? Reply YES if so, or NO if you do not recognize the transaction.

The affirmative response followup is sent when the cardholder responds YES. This message should instruct the cardholder to retry the transaction. For example:

Thank you for confirming, please wait a few moments and retry the transaction.

The negative response followup is sent when the cardholder responds NO. This message should instruct the cardholder to contact their card issuer. For example:

Thank you for confirming. This transaction was declined. Contact your card issuer immediately to secure your account.

Template Variables

The initial challenge message template supports the following variables, which are automatically replaced with transaction and card details at send time:

Default template:

Did you attempt a {{AMOUNT}} transaction at {{MERCHANT}}? Reply YES if you did, NO if not.

If a variable's underlying value is unavailable (e.g., no memo set on the card), it is replaced with an empty string. The {{MERCHANT}} and {{MEMO}} substitutions are individually capped at 25 and 30 characters respectively before being inserted into the template, so unusually long merchant names or memos do not, on their own, exceed the per-message limit.

Each of the three messages is capped at 160 characters to prevent segmentation into multiple SMS parts. After variable substitution, if the rendered message still exceeds 160 characters, Lithic truncates it to the first 160 characters and delivers the truncated message; the message is not blocked, but the trailing content (which may include the YES/NO instruction) can be lost. When authoring a template, leave enough headroom for the maximum-length substitutions: 25 characters for {{MERCHANT}}, 30 characters for {{MEMO}}, and the longest amount you expect (for example, $1,234,567.89 USD). Lithic will test message templates with representative merchant names and transaction amounts during implementation to verify they fit.

Integration with Transactions API

Lithic evaluates all authorization rules in parallel and applies the strictest decision across all rule evaluations. If one rule evaluates to decline and another rule evaluates to challenge, the transaction will be declined without issuing a challenge.

Challenged transactions contain specific decline indicators within the transaction object. The transaction result field contains DECLINED, but the detailed_results array includes the reason code corresponding with the specific scenario. For authorization rules, the rule_results array provides attribution to the specific rule that triggered challenge initiation.

Example transaction response for a challenged transaction:

{
  "token": "a4e8dc9a-f821-4365-b6a9-a6219b105b6d",
  "result": "DECLINED",
  "status": "DECLINED",
  "events": [
    {
      "token": "bbbf1e86-322d-11ee-9779-00505685a123",
      "type": "AUTHORIZATION",
      "result": "DECLINED",
      "detailed_results": ["CARDHOLDER_CHALLENGED"],
      "rule_results": [
        {
          "auth_rule_token": "ef49df0c-ed17-44cb-811b-6de1ec0f088a",
          "name": "High-Risk Transaction Challenge",
          "result": "CARDHOLDER_CHALLENGED",
          "explanation": "All conditions satisfied: TRANSACTION_AMOUNT=50001, RISK_SCORE=701"
        }
      ]
    }
  ]
}

When challenge initiation fails (for example, under Lithic Orchestration when a cardholder phone number is missing), the detailed_results array contains CARDHOLDER_CHALLENGE_FAILED.

After a cardholder successfully completes a challenge and retries the transaction, the rule that previously challenged the same transaction at the same merchant will now allow the authorization to proceed. This scenario is noted in the explanation.

Example transaction response when challenge is bypassed:

{
  "token": "b5f9ed0b-a932-5476-c7b0-b7320c216c7e",
  "result": "APPROVED",
  "status": "APPROVED",
  "events": [
    {
      "token": "ccc02f97-433e-22ff-0880-11616796b234",
      "type": "AUTHORIZATION",
      "result": "APPROVED",
      "detailed_results": ["APPROVED"],
      "rule_results": [
        {
          "auth_rule_token": "ef49df0c-ed17-44cb-811b-6de1ec0f088a",
          "name": "High-Risk Transaction Challenge",
          "result": "CARDHOLDER_CHALLENGED",
          "explanation": "All conditions satisfied: TRANSACTION_AMOUNT=50001, RISK_SCORE=701. Challenge was recently completed; approved instead."
        }
      ]
    }
  ]
}

Getting Started

Contact your program's Customer Success Manager to enable authorization challenges for your instance. Your CSM will walk you through the implementation process, including selecting the orchestration model (Lithic or Customer), configuring SMS templates for Lithic Orchestration, or wiring up the webhook and challenge response endpoint for Customer Orchestration.

Refer to the Auth Rules API documentation, the ASA specification, and the Respond to Authorization Challenge endpoint for complete API specifications.