Auth Stream Access (ASA)

Learn about providing your own authorization rules by registering an endpoint.

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 users, 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).

  1. NodeJS example: https://github.com/lithic-com/asa-demo-node
  2. 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": Float,
  "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_feeFee (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.
amountAuthorization amount of the transaction (in cents), including any acquirer fees. This may change over time.
authorization_amountThe 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.
avsContains address validation (AVS) information collected by the merchant to be verified by the issuer.
cardSee Cards Schema. Only a subset of fields from the card object are included in ASA requests: hostname, last_four, memo, spend_limit, spend_limit_duration, state, token, and type.
cardholder_authenticationSee Cardholder Authentication Schema.
cash_amountThe 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_rateIf 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.
createdDate and time when the transaction first occurred.
eventsA 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 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.
merchantSee Merchant Schema.
merchant_amountThe 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_currencyISO 4217 alpha 3 code for the currency of the transaction.
networkCard network of the authorization. Can be INTERLINK, MAESTRO, MASTERCARD, VISA, or UNKNOWN.
network_risk_scoreNetwork-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. Only available on authorizations with status of AUTHORIZATION (i.e., dual message purchase authorizations), and currently on Mastercard BINs.
posSee Point of Sale definition.
settled_amountAmount (in cents) of the transaction that has been settled, including any acquirer fees. This may change over time.
statusAvailable to all users:
AUTHORIZATION is a dual message purchase authorization.
FINANCIAL_AUTHORIZATION is a single message authorization request with no subsequent clearing.
BALANCE_INQUIRY is a $0 authorization that includes a request for the balance held on the card.

Only available to users with credit decisioning via ASA enabled:
CREDIT_AUTHORIZATION is a dual message request from a merchant to authorize a refund or credit.
FINANCIAL_CREDIT_AUTHORIZATION is a single message request from a merchant to credit funds with no subsequent clearing.
tokenGlobally unique identifier for the transaction.
token_info.wallet_typeWill 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.

User 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)The ASA responder 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 within 5 seconds, the transaction will be declined for the cardholder. Every party involved in the transaction processing flow takes a certain amount of time, and the merchant or the acquirer will time out at some point. We recommend responding within 3 seconds. If your ASA responder takes longer than that, you may see a higher percentage of transactions being voided shortly after you have approved them.

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 to the network as a response.

Enumerations

Point of Sale

terminal.attendedTrue if a clerk is present at the sale.
terminal.on_premiseTrue if the sale was made at the place of business (vs. mobile).
terminal.operatorThe person that is designed to swipe the card, possible values: CARDHOLDER, CARD_ACCEPTOR, ADMINISTRATIVE.
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.

See Partial Approval for more information on how to partially approve authorizations.
terminal.pin_capabilityStatus of whether the POS is able to accept PINs, possible values: CAPABLE, INOPERATIVE, NOT_CAPABLE, UNSPECIFIED.
terminal.typePOS type, see POS Type for possible values.
entry_mode.cardCard status, possible values: PRESENT, NOT_PRESENT.
entry_mode.cardholderCardholder Presence status, see Cardholder Presence Status for possible values.
entry_mode.panMethod of entry for the PAN, see Method of Entry for possible values.
entry_mode.pin_enteredTrue if the PIN was entered.

POS Type

  • ATM
  • AUTHORIZATION
  • COUPON_MACHINE
  • DIAL_TERMINAL
  • ECOMMERCE
  • ECR (electronic cash register)
  • 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 entryDescription
AUTO_ENTRYPAN auto-entry via server (issuer, acquirer, or third party vendor system)
BAR_CODEPAN auto-entry via bar code or QR code reader
CONTACTLESSContactless via chip
CREDENTIAL_ON_FILECredential on file
ECOMMERCEPAN or token entry via electronic commerce
ERROR_KEYEDChip 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_STRIPEChip 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
ICCPAN auto-entry via chip
KEY_ENTEREDManually keyed
MAGNETIC_STRIPEMagnetic stripe entry
MANUALManual entry
OCRPAN auto-entry via OCR
SECURE_CARDLESSSecure cardless entry
UNSPECIFIEDUnspecified method of entry
UNKNOWNUnknown or unmapped method of entry

Cardholder Presence Status

Cardholder presence statusDescription
DEFERRED_BILLINGDeferred billing payment
ELECTRONIC_ORDERCardholder not present; electronic order (e.g., via home PC, Internet, mobile phone, PDA)
INSTALLMENTInstallment payment
MAIL_ORDERCardholder not present; mail or facsimile order
NOT_PRESENTCardholder not present; unspecified
PRESENTCardholder present
REOCCURRINGStanding order or recurring transaction
TELEPHONE_ORDERCardholder not present; phone or Automated Response Unit (ARU) order

ASA Response Result

Decline reasonDescription
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.
CARD_CLOSEDCard is permanently closed. Use the Update Card to close card after sending this response.
CARD_PAUSEDCard is not yet activated or in a paused state. Use the Update Card to pause card after sending this response.
INSUFFICIENT_FUNDSUser has insufficient funds. Acquirers may retry the transaction at a later time.
UNAUTHORIZED_MERCHANTCan be used for restricted MCCs, countries, or transaction types (e.g. money transfer transactions).
VELOCITY_EXCEEDEDTransaction 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

ValueDescription
MASTERPASSNot currently used, reserved for future use.
APPLE_PAYTransaction originated from an Apple Pay wallet.
GOOGLE_PAYTransaction originated from a Google Pay wallet.
SAMSUNG_PAYTransaction originated from a Samsung Pay wallet.
MERCHANTTransaction originated from a merchant token.
OTHERTransaction originated from an unknown but tokenized source.

ASA Webhook Verification

Lithic enables webhook verification for ASA requests using the same methodology that is used in our Events API and webhooks. Please refer to this page for detailed implementation steps and example code you can use.

By default, the three headers (webhook-id, webhook-timestamp, and webhook-signature) are not included in ASA requests. To begin receiving these headers, call the retrieve the ASA HMAC secret key endpoint. Within minutes, the headers will begin appearing in your ASA requests. To rotate your key, call the rotate the ASA HMAC secret key endpoint. Both of these endpoints (as well as simulated ASA requests) are available in Sandbox, and we recommend testing your implementation of webhook verification in the Sandbox environment first.

You can also retrieve these keys on the account page of the Lithic Dashboard. Note that a Production key will only appear once your card program is configured by your Implementation Manager to have ASA enabled, and a Sandbox key will only appear once you have enrolled in Sandbox ASA via the Enroll ASA endpoint.