Authorization Stream Access (ASA) provides the ability to make custom transaction approval decisions through an HTTP interface to the ISO 8583 message stream.

ASA requests are delivered as an HTTP POST during authorization. The ASA request body adheres to the Lithic transaction schema, with some additional fields added for use in decisioning. A response should be sent with HTTP response code 200 and the approval decision in the response body. This response is converted by Lithic back into ISO-8583 format and forwarded to the network.

📘
In sandbox, users can self-enroll and disenroll in ASA; API reference: Auth Stream Access (ASA). In production, onboarding requires manual approval and setup.

📘
For ASA enabled customers, Lithic won't check auth rules such as MERCHANT_LOCKED. You must supply your own auth rules.

Schema

Lithic Request

Similar to Transaction object for Transaction Webhook with additional properties.

{
  "amount": Integer,
  "acquirer_fee": Integer,
  "authorization_amount": Integer,
  "card": Card,
  "created": String,
  "events": [
      Event
  ],
  "funding": [
      {
          "amount": Integer,
          "token": String,
          "type": String
      }
  ],
  "merchant": Merchant,
  "pos": {
      "terminal": {
          "attended": Boolean,
          "operator": String,
          "on_premise": Boolean,
          "card_retention_capable": Boolean,
          "pin_capability": String,
          "type": String,
          "partial_approval_capable": Boolean
      },
      "entry_mode": {
          "pan": String,
          "pin_entered": Boolean,
          "cardholder": String,
          "card": String
      }
  },
  "avs": {
      "zipcode": String,
      "address": String
  },
  "settled_amount": Integer,
  "status": String,
  "token": String
}


amount	Authorization amount (in cents) of the transaction. This may change over time
aquirer_fee	Fee 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	The base transaction amount 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
card	See Card schema definition
created	Date and time when the transaction first occurred
events (Issuing)	A list of all events that have modified this transaction
funding	A list of objects that describe how this transaction was funded, with the `amount` represented in cents. A reference to the funding account for the card that made this transaction may appear here and the `token` will match the `token` for the funding account in the `card` field. If any promotional credit was used in paying for this transaction, its `type` will be `PROMO`
merchant	See Merchant definition in Transaction
pos	See Point of Sale definition in Transaction
avs	Contains validation information entered by the client to be verified by the issuer
settled_amount	Amount (in cents) of the transaction that has been settled. This may change over time
status	`AUTHORIZATION`, `FINANCIAL_AUTHORIZATION`, and `BALANCE_INQUIRY` indicates that this request requires an ASA response body in HTTP 200 response. `FINANCIAL_AUTHORIZATION` is a final single-message transaction with no subsequent clearing, `BALANCE_INQUIRY` is a $0 authorization that should prompt a response with the appropriate balance
token	Globally unique identifier

Client Response

{
  "result": String,
  "token": String,
  "avs_result": String,
  "balance": {
      "amount": Integer,
      "available": Integer
  }
}


result	`APPROVED` to accept the authorization. Any other response will decline the authorization. See ASA Response Result for possible values
token	The transaction token from the ASA request
avs_result (optional)	ASA client may return `APPROVED` with AVS match indicator that can be evaluated by the acquirer. See AVS Response Result for possible values
balance (optional)	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 POS/ATM

Response Guidelines

Response Time

The request timeout is configurable per request, with a default of 5 seconds. Response before the timeout does not guarantee that the authorization will succeed.

AVS Matching

AVS response is optional. If AVS is present and a response is not received, Lithic will return AVS validated.
If AVS attributes aren’t included in the authorization, any AVS response result will be ignored.

Returned Balances

BALANCE_INQUIRY ASA messages require a settled and available amount to be returned.

amount represents the balance held on the card.
available represents the balance available for the cardholder to spend. This is calculated as the settled amount minus any pending authorizations on the card.

If no balance is returned, Lithic will return $0 for both attributes.

Enumerations

Point of Sale


terminal.attended	True if a clerk is present at the sale
terminal.operator	The person that is designed to swipe the card, possible values: `CARDHOLDER`, `CARD_ACCEPTOR`, `ADMINISTRATIVE`
terminal.on_premise	True if the sale was made at the place of business (vs. mobile)
terminal.pin_capability	Status of whether the POS is able to accept PINs, possible values: `UNSPECIFIED`, `NOT_CAPABLE`, `CAPABLE`, `INOPERATIVE`
terminal.type	POS type, see POS Type for possible values
terminal.partial_approval_capable	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.
entry_mode.pan	Method of entry for the PAN, see Method of Entry for possible values
entry_mode.pin_entered	True if the PIN was entered
entry_mode.cardholder	Cardholder status, see Cardholder Status for possible values
entry_mode.card	Card status, possible values: `PRESENT`, `NOT_PRESENT`, `PREAUTHORIZED`

📘
Partial approval is currently not supported.

POS Type

POS_TERMINAL
ATM
HOME_TERMINAL
ECR
DIAL_TERMINAL
PHONE
TELEVISION
TRAVELERS_CHECK_MACHINE
FUEL_MACHINE
COUPON_MACHINE
TELLER
POINT
MICR
OFF_PREMISE
VENDING
SELF_SERVICE
AUTHORIZATION
PAYMENT
VOICE
PDA
ECOMMERCE

Method of Entry

UNSPECIFIED
MANUAL
MAGNETIC_STRIPE
BAR_CODE
OCR
ICC
KEY_ENTERED
CONTACTLESS
ECOMMERCE
ERROR_KEYED
ERROR_MAGNETIC_STRIPE
AUTO_ENTRY
SECURE_CARDLESS

Cardholder Status

PRESENT
NOT_PRESENT
MAIL_ORDER
TELEPHONE_ORDER
REOCCURRING
PREAUTHORIZED
DEFERRED_BILLING
INSTALLMENT

ASA Response Result


Decline reason	Description
CARD_CLOSED	Card is permanently closed. Using `CARD_CLOSED` will result in subsequent authorizations being declined on the ASA client's behalf
CARD_PAUSED	Card is not yet activated, or in a paused state
ACCOUNT_INACTIVE	Same as `CARD_PAUSED`, will be deprecated in future versions
AVS_INVALID	Prevent acquirers from approving the transaction despite incorrect AVS. Note: AVS response is not required for this decline type
VELOCITY_EXCEEDED	Transaction exceeds issuer-set velocity limits. Acquirers may retry the transaction at a later date
UNAUTHORIZED_MERCHANT	Can be used for restricted MCCs, countries, or transaction types (e.g. money transfer transactions)
INSUFFICIENT_FUNDS	User has insufficient funds. Acquirers may retry the transaction at a later time
MALFORMED_RESPONSE	The response to Lithic's Auth Stream Access (ASA) request was malformed.

AVS Response Result


MATCH
FAIL
MATCH_ADDRESS_ONLY
MATCH_ZIP_ONLY