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.

📘
Testing in sandbox
In sandbox, users can self-enroll and disenroll in ASA. In production, onboarding requires manual approval and setup.

🚧
Pre-ASA auth request checks
For ASA-enabled customers, Lithic will only perform very basic pre-authorization checks before sending the request out (decrypt EMV cryptogram, validate PAN, validate CVV/PIN if present). For example, we won't check auth rules such as MERCHANT_LOCKED or spending limits. You must supply your own auth rules.
Lithic will not send ASA requests to your endpoint if the message fails basic pre-authorization checks. For a list of all pre-authorization checks, please reference Transaction.result.

Set up an ASA responder in under 10 minutes!

Full details on responding to ASA requests follow, but to get you up and running quickly we’ve also provided sample application for creating an auth stream access webhook with AWS API Gateway and Lambda, managed via AWS Serverless Application Model (SAM).

NodeJS example: https://github.com/lithic-com/asa-demo-node
Python example: https://github.com/lithic-com/asa-demo-python

Schema

Lithic Request

Similar to Transaction object in Transaction Webhooks with additional properties.

{
  "amount": Integer,
  "acquirer_fee": Integer,
  "authorization_amount": Integer,
  "avs": {
      "address": String,
      "zipcode": String
  },
  "card": Card,
  "cardholder_authentication": CardholderAuthentication,
  "cash_amount": Integer,
  "conversion_rate": Integer,
  "created": String,
  "events": [
      Event
  ],
  "funding": [
      {
          "amount": Integer,
          "token": String,
          "type": String
      }
  ],
  "merchant_amount": Integer,
  "merchant_currency": String,
  "merchant": Merchant,
  "network": String,
  "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
      }
  },
  "settled_amount": Integer,
  "status": String,
  "token": String,
  "token_info": {
    "wallet_type": Enum{}
  }
}


acquirer_fee	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.
amount	Authorization amount of the transaction (in cents), including any acquirer fees. This may change over time.
authorization_amount	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.
avs	Contains address validation (AVS) information entered by the client to be verified by the issuer.
card	See Cards Schema.
cardholder_authentication	See Cardholder Authentication Schema.
cash_amount	The portion of the transaction requested as cash back by the cardholder, and does not include any acquirer fees. The `amount` field includes the purchase amount, the requested cash back amount, and any acquirer fees. If no cash back was requested, the value of this field will be `0`, and the field will always be present.
conversion_rate	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`. Note that the `merchant_amount` is in the local currency and the `amount` is in the settlement currency.
created	Date and time when the transaction first occurred.
events	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 source for the card that made this transaction may appear here and the `token` will match the `token` for the funding source in the `card` field. If any promotional credit was used in paying for this transaction, its `type` will be `PROMO`.
merchant	See Merchant Schema.
merchant_amount	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	ISO 4217 alpha 3 code for the currency of the transaction.
network	Card network of the authorization. Can be `INTERLINK`, `MAESTRO`, `MASTERCARD`, `VISA`, or `UNKNOWN`.
pos	See Point of Sale definition.
settled_amount	Amount (in cents) of the transaction that has been settled, including any acquirer fees. 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.
token_info.wallet_type	Will be present if the transaction is tokenized, and absent for a physical or virtual non-tokenized transaction. 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.

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)	The ASA client may return an address verification (AVS) match indicator for evaluation by the acquirer. See AVS Response Result for possible values. The merchant can choose whether to submit the transaction in the case of an approval with AVS failure.
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 point of sale or ATM.

Response Guidelines

Response Time

If no response is received, the transaction will timeout resulting in a decline for the cardholder. The ASA request timeout is configurable, with a default of 5 seconds. Response before the timeout does not guarantee that the authorization will succeed. Even in the case that the timeout is changed, we recommend responding in less than 5 seconds to ensure that all merchants will process the transaction.

AVS Matching

Address verification (AVS) checks two pieces of information, the postal code and the billing street address. Responding with AVS 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.on_premise	True if the sale was made at the place of business (vs. mobile).
terminal.operator	The person that is designed to swipe the card, possible values: `CARDHOLDER`, `CARD_ACCEPTOR`, `ADMINISTRATIVE`.
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. See Partial Approval for more information on how to partially approve authorizations.
terminal.pin_capability	Status of whether the POS is able to accept PINs, possible values: `CAPABLE`, `INOPERATIVE`, `NOT_CAPABLE`, `UNSPECIFIED`.
terminal.type	POS type, see POS Type for possible values.
entry_mode.card	Card status, possible values: `PRESENT`, `NOT_PRESENT`.
entry_mode.cardholder	Cardholder status, see Cardholder Status for possible values.
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.

📘
Partial approval is currently not supported.

POS Type

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

Method of Entry


Method of entry	Description
`AUTO_ENTRY`	PAN auto-entry via server (issuer, acquirer, or third party vendor system)
`BAR_CODE`	PAN auto-entry via bar code or QR code reader
`CONTACTLESS`	Contactless via chip
`ECOMMERCE`	PAN or token entry via electronic commerce
`ERROR_KEYED`	Chip card or chip-capable terminal was unable to process the transaction using the data on the chip or magnetic stripe, the PAN was entered manually, or the acquirer is not certified to process chip fallback to magnetic stripe
`ERROR_MAGNETIC_STRIPE`	Chip card or chip-capable terminal was unable to process the transaction using the data on the chip, therefore the PAN was entered via magnetic stripe
`ICC`	PAN auto-entry via chip
`KEY_ENTERED`	Manually keyed
`MAGNETIC_STRIPE`	Magnetic stripe entry
`MANUAL`	Manual entry
`OCR`	PAN auto-entry via OCR
`SECURE_CARDLESS`	Secure cardless entry
`UNSPECIFIED`

Cardholder Status

DEFERRED_BILLING
INSTALLMENT
MAIL_ORDER
NOT_PRESENT
PRESENT
REOCCURRING
TELEPHONE_ORDER

ASA Response Result


Decline reason	Description
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.
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.
INSUFFICIENT_FUNDS	User has insufficient funds. Acquirers may retry the transaction at a later time.
UNAUTHORIZED_MERCHANT	Can be used for restricted MCCs, countries, or transaction types (e.g. money transfer transactions).
VELOCITY_EXCEEDED	Transaction exceeds issuer-set velocity limits. Acquirers may retry the transaction at a later date.

AVS Response Result


FAIL
MATCH
MATCH_ADDRESS_ONLY
MATCH_ZIP_ONLY

Wallet Type

Value	Description
`MASTERPASS`	Not currently used, reserved for future use.
`APPLE_PAY`	Transaction originated from an Apple Pay wallet.
`GOOGLE_PAY`	Transaction originated from a Google Pay wallet.
`SAMSUNG_PAY`	Transaction originated from a Samsung Pay wallet.
`MERCHANT`	Transaction originated from a merchant token.
`OTHER`	Transaction originated from an unknown but tokenized source.

Auth Stream Access (ASA)

📘
Testing in sandbox

🚧
Pre-ASA auth request checks

Set up an ASA responder in under 10 minutes!

Schema

Lithic Request

Client Response

Response Guidelines

Response Time

AVS Matching

Returned Balances

Enumerations

Point of Sale

📘

POS Type

Method of Entry

Cardholder Status

ASA Response Result

AVS Response Result

Wallet Type

📘Testing in sandbox

🚧Pre-ASA auth request checks

Set up an ASA responder in under 10 minutes!

Schema

Lithic Request

Client Response

Response Guidelines

Response Time

AVS Matching

Returned Balances

Enumerations

Point of Sale

📘

POS Type

Method of Entry

Cardholder Status

ASA Response Result

AVS Response Result

Wallet Type

📘
Testing in sandbox

🚧
Pre-ASA auth request checks