Sign in

v66

latestOpenAPI 3.1.0Apache 2.0raw.githubusercontent.com2026-08-042174421.1 MB
Auth Stream Access (ASA)

Auth Stream Access Request

Auth Stream Access Request

postWebhookcard_authorization.approval_request

Headers

webhook-idstring uuid

Webhook ID

webhook-timestampinteger

Unix timestamp used for HMAC verification

webhook-signaturestring

A list of HMAC signatures encoded in Base64 and separated by spaces. Can contain multiple HMAC signatures as a result of key rotation.

Payload

event_type'card_authorization.approval_request' required
amountinteger required

Deprecated, use amounts. Authorization amount of the transaction (in cents), including any acquirer fees. The contents of this field are identical to authorization_amount.

acquirer_feeinteger required

Fee (in cents) assessed by the merchant and paid for by the cardholder. Will be zero if no fee is assessed. Rebates may be transmitted as a negative value to indicate credited fees.

authorization_amountinteger required

Deprecated, use amounts. The base transaction amount (in cents) plus the acquirer fee field. This is the amount the issuer should authorize against unless the issuer is paying the acquirer fee on behalf of the cardholder.

cardholder_currencystring required

Deprecated, use amounts. 3-character alphabetic ISO 4217 code for cardholder's billing currency.

cash_amountinteger required

The amount of cash requested by the cardholder, in the cardholder billing currency's smallest unit. For purchase-with-cashback transactions this is the cashback portion only; for ATM transactions this is the full amount. This amount includes all acquirer fees.

If no cash was requested, the value of this field will be 0, and the field will always be present.

cashbackinteger

Deprecated, use cash_amount.

ttlstring date-time

Deprecated: approximate time-to-live for the authorization.

conversion_ratenumber

Deprecated, use amounts. If the transaction was requested in a currency other than the settlement currency, this field will be populated to indicate the rate used to translate the merchant_amount to the amount (i.e., merchant_amount x conversion_rate = amount). Note that the merchant_amount is in the local currency and the amount is in the settlement currency.

createdstring date-time required

Date and time when the transaction first occurred in UTC.

merchant_amountinteger required

Deprecated, use amounts. The amount that the merchant will receive, denominated in merchant_currency and in the smallest currency unit. Note the amount includes acquirer_fee, similar to authorization_amount. It will be different from authorization_amount if the merchant is taking payment in a different currency.

merchant_currencystring required

3-character alphabetic ISO 4217 code for the local currency of the transaction.

network'AMEX' | 'INTERLINK' | 'MAESTRO' | 'MASTERCARD' | 'UNKNOWN' | 'VISA'

Card network of the authorization.

network_risk_scoreinteger nullable

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.

settled_amountinteger required

Deprecated, use amounts. Amount (in cents) of the transaction that has been settled, including any acquirer fees.

status'AUTHORIZATION' | 'CREDIT_AUTHORIZATION' | 'FINANCIAL_AUTHORIZATION' | 'FINANCIAL_CREDIT_AUTHORIZATION' | 'BALANCE_INQUIRY' required

The type of authorization request that this request is for. Note that CREDIT_AUTHORIZATION and FINANCIAL_CREDIT_AUTHORIZATION is only available to users with credit decisioning via ASA enabled.

tokenstring uuid required

The provisional transaction group uuid associated with the authorization

event_tokenstring uuid

The event token associated with the authorization. This field is only set for programs enrolled into the beta.

account_type'CHECKING' | 'SAVINGS'
transaction_initiator'CARDHOLDER' | 'MERCHANT' | 'UNKNOWN' required

The entity that initiated the transaction.

Example payload

{
  "event_type": "card_authorization.approval_request",
  "merchant": {
    "acceptor_id": "333301802529120",
    "acquiring_institution_id": "191231",
    "city": "NEW YORK",
    "country": "USA",
    "descriptor": "COFFEE SHOP",
    "mcc": "5812",
    "state": "NY",
    "postal_code": "10001",
    "street_address": "123 MAIN ST",
    "phone_number": "5551234567"
  },
  "cardholder_authentication": {
    "authentication_result": "SUCCESS",
    "authentication_method": "FRICTIONLESS",
    "decision_made_by": "LITHIC_RULES",
    "liability_shift": "3DS_AUTHENTICATED",
    "three_ds_authentication_token": "a6e372d0-b40a-43eb-b0d1-4e1aebef5875"
  },
  "merchant_currency": "USD",
  "amounts": {
    "cardholder": {
      "conversion_rate": "1.000000",
      "currency": "USD"
    },
    "merchant": {
      "currency": "USD"
    },
    "settlement": {
      "currency": "USD"
    },
    "hold": {
      "currency": "USD"
    }
  }
}

Response

Return a HTTP 200 status to indicate that the ASA responder was able to handle the request.

result'APPROVED' | 'AVS_INVALID' | 'CARD_PAUSED' | 'INSUFFICIENT_FUNDS' | 'UNAUTHORIZED_MERCHANT' | 'VELOCITY_EXCEEDED' | 'DRIVER_NUMBER_INVALID' | 'VEHICLE_NUMBER_INVALID' | 'SUSPECTED_FRAUD' | 'CHALLENGE' required

Result of the Authorization decision. Provide APPROVED to accept the authorization. Any other response will decline the authorization. Result CHALLENGE is valid only for cardholder-initiated transactions. If a value not present in the enumeration is returned the transaction will be declined with the CUSTOM_ASA_RESULT detailed result.

tokenstring uuid

The transaction token from the ASA request.

approved_amountinteger

The amount approved for the transaction. Note that setting this implies a partial approval. This property should not be present if the intention is to fully approve the transaction. See: https://docs.lithic.com/docs/partial-approval#partial-approval

avs_result'FAIL' | 'MATCH' | 'MATCH_ADDRESS_ONLY' | 'MATCH_ZIP_ONLY'

The ASA responder may return an address verification (AVS) match indicator for evaluation by the acquirer. The merchant can choose whether to proceed with the transaction in the case of an approval with AVS failure. When they do not, this typically appears as a subsequent AUTHORIZATION_REVERSAL event following the AUTHORIZATION. Note that AVS data submitted by merchants can be variable in quality, and we recommend card programs exercise adjust their decisioning logic accordingly.

challenge_phone_numberstring

The phone number to use for sending an Authorization Challenge SMS. Relevant only when the result is CHALLENGE. The expected format is E.164 without hyphens. For example, "+15555555555" for a US phone number.