---
title: "Auth Stream Access Request"
method: POST
path: "card_authorization.approval_request"
tags: ["Auth Stream Access (ASA)"]
---

# Auth Stream Access Request

`POST card_authorization.approval_request` (webhook)

Auth Stream Access Request

## Headers

- `webhook-id` string, uuid
- `webhook-timestamp` integer
- `webhook-signature` string

## Payload

- object — Card Authorization
  - `event_type` 'card_authorization.approval_request', required
  - `merchant` TransactionMerchant, required — Merchant information including full location details.
    - `acceptor_id` string, required — Unique alphanumeric identifier for the payment card acceptor (merchant).
    - `acquiring_institution_id` string, required — Unique numeric identifier of the acquiring institution.
    - `city` string, required — City of card acceptor. Note that in many cases, particularly in card-not-present transactions, merchants may send through a phone number or URL in this field.
    - `country` string, required — Country or 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.
    - `descriptor` string, required — Short description of card acceptor.
    - `mcc` string, required — Merchant category code (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.
    - `state` string, required — Geographic state of card acceptor.
    - `postal_code` string, nullable, required — Postal code of card acceptor.
    - `street_address` string, nullable, required — Street address of card acceptor.
    - `phone_number` string, nullable, required — Phone number of card acceptor.
  - `service_location` ServiceLocation, required — Where the cardholder received the service, when different from the card acceptor location. This is populated from network data elements such as Mastercard DE-122 SE1 SF9-14 and Visa F34 DS02.
    - `street_address` string, nullable, required — Street address of service location.
    - `city` string, nullable, required — City of service location.
    - `state` string, nullable, required — State/province code of service location, ISO 3166-2.
    - `country` string, nullable, required — Country code of service location, ISO 3166-1 alpha-3.
    - `postal_code` string, nullable, required — Postal code of service location.
  - `avs` object, required
    - `address` string, required — Cardholder address
    - `zipcode` string, required — Cardholder ZIP code
    - `address_on_file_match` 'MATCH' | 'MATCH_ADDRESS_ONLY' | 'MATCH_ZIP_ONLY' | 'MISMATCH' | 'NOT_PRESENT', required — Lithic's evaluation result comparing the transaction's address data with the cardholder KYC data if it exists. In the event Lithic does not have any Cardholder KYC data, or the transaction does not contain any address data, NOT_PRESENT will be returned
  - `card` AsaRequestCard, required — Card object in ASA
    - `last_four` string, required — Last four digits of the card number
    - `memo` string, required — Customizable name to identify the card
    - `spend_limit` integer, required — Amount (in cents) to limit approved authorizations. Purchase requests above the spend limit will be declined (refunds and credits will be approved). Note that while spend limits are enforced based on authorized and settled volume on a card, they are not recommended to be used for balance or reconciliation-level accuracy. Spend limits also cannot block force posted charges (i.e., when a merchant sends a clearing message without a prior authorization).
    - `spend_limit_duration` 'ANNUALLY' | 'FOREVER' | 'MONTHLY' | 'TRANSACTION', required — Note that to support recurring monthly payments, which can occur on different day every month, the time window we consider for MONTHLY velocity starts 6 days after the current calendar date one month prior.
    - `state` 'CLOSED' | 'OPEN' | 'PAUSED' | 'PENDING_ACTIVATION' | 'PENDING_FULFILLMENT', required
    - `type` 'SINGLE_USE' | 'MERCHANT_LOCKED' | 'UNLOCKED' | 'PHYSICAL' | 'DIGITAL_WALLET' | 'VIRTUAL', required
    - `token` string, uuid, required — Globally unique identifier for the card.
  - `cardholder_authentication` CardholderAuthentication
    - `authentication_result` 'ATTEMPTS' | 'DECLINE' | 'NONE' | 'SUCCESS', required — Indicates the outcome of the 3DS authentication process.
    - `authentication_method` 'FRICTIONLESS' | 'CHALLENGE' | 'NONE', required — Indicates the method used to authenticate the cardholder.
    - `decision_made_by` 'CUSTOMER_RULES' | 'CUSTOMER_ENDPOINT' | 'LITHIC_DEFAULT' | 'LITHIC_RULES' | 'NETWORK' | 'UNKNOWN', required — Indicates which party made the 3DS authentication decision.
    - `liability_shift` '3DS_AUTHENTICATED' | 'TOKEN_AUTHENTICATED' | 'NONE', required — Indicates whether chargeback liability shift applies to the transaction. Possible enum values: * `3DS_AUTHENTICATED`: The transaction was fully authenticated through a 3-D Secure flow, chargeback liability shift applies. * `NONE`: Chargeback liability shift has not shifted to the issuer, i.e. the merchant is liable. * `TOKEN_AUTHENTICATED`: The transaction was a tokenized payment with validated cryptography, possibly recurring. Chargeback liability shift to the issuer applies.
    - `three_ds_authentication_token` string, uuid, nullable, required — Unique identifier you can use to match a given 3DS authentication (available via the three_ds_authentication.created event webhook) and the transaction. Note that in cases where liability shift does not occur, this token is matched to the transaction on a best-effort basis.
  - `pos` object
    - `entry_mode` AsaRequestPosEntryMode — POS > Entry Mode object in ASA
      - `card` 'PRESENT' | 'NOT_PRESENT' | 'UNKNOWN' — Card Presence Indicator
      - `cardholder` 'DEFERRED_BILLING' | 'ELECTRONIC_ORDER' | 'INSTALLMENT' | 'MAIL_ORDER' | 'NOT_PRESENT' | 'PRESENT' | 'REOCCURRING' | 'TELEPHONE_ORDER' | 'UNKNOWN' — Cardholder Presence Indicator
      - `pan` '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' | 'ECOMMERCE' — Method of entry for the PAN
      - `pin_entered` boolean — Indicates whether the cardholder entered the PIN. True if the PIN was entered.
    - `terminal` AsaPosTerminal
      - `acceptor_terminal_id` string, nullable — Uniquely identifies a terminal at the card acceptor location of acquiring institutions or merchant POS Systems. Left justified with trailing spaces.
      - `attended` boolean, required — True if a clerk is present at the sale.
      - `card_retention_capable` boolean, required — True if the terminal is capable of retaining the card.
      - `on_premise` boolean, required — True if the sale was made at the place of business (vs. mobile).
      - `operator` 'ADMINISTRATIVE' | 'CARDHOLDER' | 'CARD_ACCEPTOR' | 'UNKNOWN', required — The person that is designated to swipe the card
      - `partial_approval_capable` boolean, required — True if the terminal is capable of partial approval. Partial approval is when part of a transaction is approved and another payment must be used for the remainder. Example scenario: A $40 transaction is attempted on a prepaid card with a $25 balance. If partial approval is enabled, $25 can be authorized, at which point the POS will prompt the user for an additional payment of $15.
      - `pin_capability` 'CAPABLE' | 'INOPERATIVE' | 'NOT_CAPABLE' | 'UNSPECIFIED', required — Status of whether the POS is able to accept PINs
      - `type` 'ADMINISTRATIVE' | 'ATM' | 'AUTHORIZATION' | 'COUPON_MACHINE' | 'DIAL_TERMINAL' | 'ECOMMERCE' | 'ECR' | 'FUEL_MACHINE' | 'HOME_TERMINAL' | 'MICR' | 'OFF_PREMISE' | 'PAYMENT' | 'PDA' | 'PHONE' | 'POINT' | 'POS_TERMINAL' | 'PUBLIC_UTILITY' | 'SELF_SERVICE' | 'TELEVISION' | 'TELLER' | 'TRAVELERS_CHECK_MACHINE' | 'VENDING' | 'VOICE' | 'UNKNOWN', required — POS Type
  - `amount` integer, 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_fee` integer, 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_amount` integer, 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_currency` string, required — Deprecated, use `amounts`. 3-character alphabetic ISO 4217 code for cardholder's billing currency.
  - `cash_amount` integer, 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.
  - `cashback` integer — Deprecated, use `cash_amount`.
  - `token_info` TokenInfo
    - `wallet_type` 'APPLE_PAY' | 'GOOGLE_PAY' | 'MASTERPASS' | 'MERCHANT' | 'OTHER' | 'SAMSUNG_PAY', required — The wallet_type field will indicate the source of the token. Possible token sources include digital wallets (Apple, Google, or Samsung Pay), merchant tokenization, and “other” sources like in-flight commerce. Masterpass is not currently supported and is included for future use.
  - `ttl` string, date-time — Deprecated: approximate time-to-live for the authorization.
  - `conversion_rate` number — 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.
  - `created` string, date-time, required — Date and time when the transaction first occurred in UTC.
  - `merchant_amount` integer, 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_currency` string, 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_score` integer, 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_amount` integer, required — Deprecated, use `amounts`. Amount (in cents) of the transaction that has been settled, including any acquirer fees.
  - `amounts` object, required — Structured amounts for this authorization. The `cardholder` and `merchant` amounts reflect the original network authorization values. For programs with hold adjustments enabled (e.g., automated fuel dispensers or tipping MCCs), the `hold` amount may exceed the `cardholder` and `merchant` amounts to account for anticipated final transaction amounts such as tips or fuel fill-ups
    - `cardholder` ConvertedAmount, required
      - `amount` integer, required — Amount in the smallest unit of the applicable currency (e.g., cents)
      - `conversion_rate` string, required — Exchange rate used for currency conversion
      - `currency` string, required — 3-character alphabetic ISO 4217 currency
    - `merchant` Amount, required
      - `amount` integer, required — Amount in the smallest unit of the applicable currency (e.g., cents)
      - `currency` string, required — 3-character alphabetic ISO 4217 currency
    - `settlement` Amount, required
      - `amount` integer, required — Amount in the smallest unit of the applicable currency (e.g., cents)
      - `currency` string, required — 3-character alphabetic ISO 4217 currency
    - `hold` Amount, required
      - `amount` integer, required — Amount in the smallest unit of the applicable currency (e.g., cents)
      - `currency` string, required — 3-character alphabetic ISO 4217 currency
  - `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.
  - `token` string, uuid, required — The provisional transaction group uuid associated with the authorization
  - `event_token` string, uuid — The event token associated with the authorization. This field is only set for programs enrolled into the beta.
  - `fleet_info` AsaRequestFleetInfo, nullable — Optional Object containing information if the Card is a part of a Fleet managed program
    - `driver_number` string, nullable — Number representing the driver
    - `vehicle_number` string, nullable — Number associated with the vehicle
    - `fleet_restriction_code` 'NO_RESTRICTIONS' | 'FUEL_ONLY', required — Code indicating which restrictions, if any, there are on purchase. This is configured at a program level and is a static configuration, and does not change on a request to request basis
    - `fleet_prompt_code` 'NO_PROMPT' | 'VEHICLE_NUMBER' | 'DRIVER_NUMBER', required — Code indicating what the driver was prompted to enter at time of purchase. This is configured at a program level and is a static configuration, and does not change on a request to request basis
  - `network_specific_data` AsaNetworkSpecificData, nullable — Contains raw data provided by the card network, including attributes that provide further context about the authorization. If populated by the network, data is organized by Lithic and passed through without further modification. Please consult the official network documentation for more details about these values and how to use them. This object is only available to certain programs- contact your Customer Success Manager to discuss enabling access.
    - `mastercard` AsaNetworkSpecificDataMastercard
      - `transaction_type_identifier` string, nullable — Indicates the type of additional transaction purpose.
      - `ecommerce_security_level_indicator` string, nullable — Indicates the electronic commerce security level and UCAF collection.
      - `on_behalf_service_result` object[], nullable — The On-behalf Service performed on the transaction and the results. Contains all applicable, on-behalf service results that were performed on a given transaction.
        - `service` string, required — Indicates the service performed on the transaction.
        - `result_1` string, required — Indicates the results of the service processing.
        - `result_2` string, required — Identifies the results of the service processing.
    - `visa` AsaNetworkSpecificDataVisa
      - `business_application_identifier` string, nullable — Identifies the purpose or category of a transaction, used to classify and process transactions according to Visa’s rules.
  - `account_type` 'CHECKING' | 'SAVINGS'
  - `transaction_initiator` 'CARDHOLDER' | 'MERCHANT' | 'UNKNOWN', required — The entity that initiated the transaction.
  - `latest_challenge` object — The latest Authorization Challenge that was issued to the cardholder for this merchant.
    - `status` 'COMPLETED' | 'DECLINED' | 'PENDING' | 'EXPIRED' | 'ERROR', required — The status of the Authorization Challenge * `COMPLETED` - Challenge was successfully completed by the cardholder * `DECLINED` - Challenge was declined by the cardholder * `PENDING` - Challenge is still open * `EXPIRED` - Challenge has expired without being completed * `ERROR` - There was an error processing the challenge
    - `method` 'SMS' | 'OUT_OF_BAND', required — The method used to deliver the challenge to the cardholder * `SMS` - Challenge was delivered via SMS * `OUT_OF_BAND` - Challenge was delivered via an out-of-band method
    - `phone_number` string, nullable, required — The phone number used for sending the Authorization Challenge. Present only when the challenge method is `SMS`.
    - `created` string, date-time, required — The date and time when the Authorization Challenge was created in UTC
    - `completed_at` string, date-time, nullable, required — The date and time when the Authorization Challenge was completed in UTC. Filled only if the challenge has been completed.
  - `name_validation` object, nullable, required — Network name validation data, present when the card network requested name validation for this transaction. Contains the cardholder name provided by the network and Lithic's computed match result against KYC data on file.
    - `name` object, required — Cardholder name as provided by the card network.
      - `first` string, required — First name
      - `middle` string, nullable, required — Middle name
      - `last` string, required — Last name
    - `name_on_file_match` NameValidationResult, required — Name match result comparing the cardholder name provided by the card network with the name on file from KYC data. Unverified is returned when Lithic does not have KYC data on file.
      - `full_name` 'MATCH' | 'PARTIAL_MATCH' | 'NO_MATCH' | 'UNVERIFIED', required — Overall name match result.

## Acknowledgement `200`

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

- AsaResponse — The Auth Stream Access response payload that an ASA responder may respond with in response to a 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.
  - `token` string, uuid — The transaction token from the ASA request.
  - `approved_amount` integer — 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.
  - `balance` object — Respective available amount and settled amount values (in cents). These values can be used by merchants for authorization decisions as well as balance display at point of sale or ATM.
    - `amount` integer, nullable — The balance held on the card.
    - `available` integer, nullable — The balance available for the cardholder to spend. This is calculated as the settled amount minus any pending authorizations on the card.
  - `challenge_phone_number` string — 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.
  - `name_validation_result` NameValidationResult — Name match result comparing the cardholder name provided by the card network with the name on file from KYC data. Unverified is returned when Lithic does not have KYC data on file.
    - `full_name` 'MATCH' | 'PARTIAL_MATCH' | 'NO_MATCH' | 'UNVERIFIED', required — Overall name match result.

## Other responses

- `5XX` — Return a HTTP 5XX response to indicate processing failure. This will cause Lithic to immediately retry the request once.

---

[API](https://skmtc.net/lithic-com/apis/lithic-developer-api.md) · [All operations](https://skmtc.net/lithic-com/apis/lithic-developer-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/lithic-com/lithic-developer-api/revisions/53ab5d4e2adb/schema)