Auth Stream Access (ASA)

Learn about providing your own auth rules.

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
}
amountAuthorization amount (in cents) of the transaction. This may change over time
aquirer_feeFee 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_amountThe 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
cardSee Card schema definition
createdDate and time when the transaction first occurred
events (Issuing) A list of all events that have modified this transaction
fundingA 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
merchantSee Merchant definition in Transaction
posSee Point of Sale definition in Transaction
avsContains validation information entered by the client to be verified by the issuer
settled_amountAmount (in cents) of the transaction that has been settled. This may change over time
statusAUTHORIZATION, 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
tokenGlobally unique identifier

Client Response

{
  "result": String,
  "token": String,
  "avs_result": String,
  "balance": {
      "amount": Integer,
      "available": Integer
  }
}
resultAPPROVED to accept the authorization. Any other response will decline the authorization. See ASA Response Result for possible values
tokenThe 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.attendedTrue if a clerk is present at the sale
terminal.operatorThe person that is designed to swipe the card, possible values: CARDHOLDER, CARD_ACCEPTOR, ADMINISTRATIVE
terminal.on_premiseTrue if the sale was made at the place of business (vs. mobile)
terminal.pin_capabilityStatus of whether the POS is able to accept PINs, possible values: UNSPECIFIED, NOT_CAPABLE, CAPABLE, INOPERATIVE
terminal.typePOS type, see POS Type for possible values
terminal.partial_approval_capableTrue 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.panMethod of entry for the PAN, see Method of Entry for possible values
entry_mode.pin_enteredTrue if the PIN was entered
entry_mode.cardholderCardholder status, see Cardholder Status for possible values
entry_mode.cardCard 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 reasonDescription
CARD_CLOSEDCard is permanently closed. Using CARD_CLOSED will result in subsequent authorizations being declined on the ASA client's behalf
CARD_PAUSEDCard is not yet activated, or in a paused state
ACCOUNT_INACTIVESame as CARD_PAUSED, will be deprecated in future versions
AVS_INVALIDPrevent acquirers from approving the transaction despite incorrect AVS. Note: AVS response is not required for this decline type
VELOCITY_EXCEEDEDTransaction exceeds issuer-set velocity limits. Acquirers may retry the transaction at a later date
UNAUTHORIZED_MERCHANTCan be used for restricted MCCs, countries, or transaction types (e.g. money transfer transactions)
INSUFFICIENT_FUNDSUser has insufficient funds. Acquirers may retry the transaction at a later time
MALFORMED_RESPONSEThe response to Lithic's Auth Stream Access (ASA) request was malformed.

AVS Response Result

MATCH
FAIL
MATCH_ADDRESS_ONLY
MATCH_ZIP_ONLY

Did this page help you?