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 both sandbox and production, users can self-enroll and disenroll in ASA.

🚧
Pre-ASA request checks
For ASA-enabled users, Lithic only performs a limited set of pre-authorization checks before sending the ASA request. Specifically, card merchant locking and account spend velocity are not checked.
Lithic will not send ASA requests to your endpoint if the message fails 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,
  "cardholder_currency": String,
  "cash_amount": Integer,
  "conversion_rate": Float,
  "created": String,
  "events": [
      Event
  ],
  "fleet_info": FleetInfo,
  "funding": [
      {
          "amount": Integer,
          "token": String,
          "type": String
      }
  ],
  "merchant_amount": Integer,
  "merchant_currency": String,
  "merchant": Merchant,
  "network": String,
  "network_risk_score": Integer,
  "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 collected by the merchant to be verified by the issuer.
card	See 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_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` (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	Date and time when the transaction first occurred.
events	A list of all events that have modified this transaction.
fleet_info	Extra information if the Card is a part of a Fleet program. See Fleet Info
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`.
network_risk_score	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. A score may not be available for all authorizations, and where it is not, this field will be set to `null`.
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	Available 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.
token	Globally unique identifier for the transaction.
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.

Cardholder Authentication Schema

Lithic provides metadata on authentication attempts. These fields can be used to determine if cardholder authentication was performed prior to the authorization being submitted by the merchant. Cardholder authentication could happen via:

3-D Secure programs, such as Mastercard Secure Code or Identity Check
Digital Secure Remote Payments (DSRP) tokenized payments via Apple Pay wallets

If the cardholder is authenticated or the merchant attempts authentication and the issuer declines to verify, liability shift may apply. If it does, the merchant no longer has liability for the transaction and it cannot be charged back for fraud.

In the ASA request, if no cardholder authentication has taken place, this object will not be included in the payload. In the transaction object, if no cardholder authentication has taken place, this object will be set to null.

{
  "verification_attempted": String,
  "verification_result": String,
  "liability_shift": String,
  "3ds_version": String,
  "acquirer_exemption": String,
  "authentication_result": String,
  "decision_made_by": String,
  "three_ds_authentication_token": String
}


`acquirer_exemption`	Will always be `NONE`, reserved for future use. - `NONE`: No exemption applied
`authentication_result`	Indicates what the outcome of the 3DS authentication process is. Possible values: `SUCCESS`: 3DS authentication was successful and the transaction is considered authenticated `DECLINE`: 3DS authentication was attempted but was unsuccessful — i.e., the issuer declined to authenticate the cardholder; note that Lithic populates this value on a best-effort basis based on common data across the 3DS authentication and ASA data elements `ATTEMPTS`: 3DS authentication was attempted but full authentication did not occur. A proof of attempted authenticated is provided by the merchant. `NONE`: 3DS authentication was not performed on the transaction
`decision_made_by`	Indicates which party made the 3DS authentication decision (see 3DS Decisioning for more details). Possible values: `NETWORK`: A network stand-in service decided on the outcome; for token authentications (as indicated in the `liability_shift` field), this is the default value `LITHIC_DEFAULT`: A default decision was made by Lithic, without running a rules-based authentication; this value will be set on card programs that do not participate in one of our two 3DS product tiers `LITHIC_RULES`: A rules-based authentication was conducted by Lithic and Lithic decided on the outcome `CUSTOMER_ENDPOINT`: Lithic customer decided on the outcome based on a real-time request sent to a configured endpoint `UNKNOWN`: Data on which party decided is unavailable
`liability_shift`	Indicates whether liability shift to the issuer applies to the transaction. Possible values: `NONE`: Liability has not shifted to the issuer (i.e. the merchant is liable) `3DS_AUTHENTICATED`: Fully authenticated (possibly recurring) transaction. Liability shift applies `TOKEN_AUTHENTICATED`: Tokenized Payment with validated cryptography, possibly recurring, liability shift applies
`three_ds_authentication_token`	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.
`3ds_version` (deprecated)	3DS Protocol Version. Note that this field may appear as `three_ds_version` in some of Lithic's client libraries. - `1`: 3DS V1 was used. `2`: 3DS V2 (EMV) was used. `null`: No 3DS was used.
`verification_attempted` (deprecated)	Indicates whether a 3DS challenge flow was used, and if so, what the verification method was. Possible values: `NONE`: Cardholder verification was not attempted. Authentication was performed via a frictionless flow, not attempted, or via standin risk-based authentication (RBA) `OTHER`: An undefined method, such as a previously challenged recurring transaction, was used to verify the cardholder
`verification_result` (deprecated)	Indicates whether a transaction is considered 3DS authenticated. `SUCCESS`: Authentication Verification Successful `FRICTIONLESS`: Attempts Processing Performed; Not Authenticated/Verified, but merchant attempted authentication/verification is provided `NOT_ATTEMPTED`: A 3DS attempt was not made for this transaction.

Merchant Schema

{
  "acceptor_id": String,
  "acquiring_institution_id": String,
  "city": String,
  "country": String,
  "descriptor": String,
  "mcc": String,
  "state": String
}


acceptor_id	Alphanumeric identifier for the payment card acceptor (merchant) which is unique within the namespace of the acquiring institution.
acquiring_institution_id	Unique alphanumeric identifier assigned to the acquiring bank or financial institution that processes credit card transactions on behalf of the payment card acceptor (merchant).
city	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. As additional events are added to the transaction object (e.g., clearing event), this field may be updated to reflect the most recent merchant data provided by the network.
country	Country or entity of card acceptor. Possible values are: (1) all ISO 3166-1 alpha-3 country codes - see here for full list, (2) `QZZ` for Kosovo, and (3) `ANT` for Netherlands Antilles. As additional events are added to the transaction object (e.g., clearing event), this field may be updated to reflect the most recent merchant data provided by the network.
descriptor	Short description of card acceptor. As additional events are added to the transaction object (e.g., clearing event), this field may be updated to reflect the most recent merchant data provided by the network.
mcc	Merchant category code.
state	Geographic state of card acceptor. As additional events are added to the transaction object (e.g., clearing event), this field may be updated to reflect the most recent merchant data provided by the network.

Fleet Info

{
  "driver_number": String,
  "vehicle_number": String,
  "fleet_restriction_code": Enum,
  "fleet_prompt_code": Enum
}


driver_number	ID representing the driver or null if not provided as part of the transaction
vehicle_number	ID or number associated with the vehicle or null if not provided as part of the transaction
fleet_restriction_code	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. `NO_RESTRICTIONS` `FUEL_ONLY`
fleet_prompt_code	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 `NO_PROMPT` `VEHICLE_NUMBER` `DRIVER_NUMBER`

User 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 (optional)	The 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 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 (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 6 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.

If both the address line and ZIP code is available in the ASA request, ASA responders should respond with MATCH.
Responding with MATCH_ZIP_ONLY indicates a "MATCH" on ZIP but a mismatch on the address line.
Responding with MATCH_ADDRESS_ONLY indicates a "MATCH" on the address line, but a mismatch on ZIP.

Lithic's default behavior for an approval when an ASA responder does not include an AVS response result is to respond to the networks based on what information is available in the authorization request. For example, if both address and zip are available, Lithic will respond to the network with MATCH. If only the ZIP is provided, Lithic will only indicate that there was a match on ZIP. If only an address line was provided, Lithic will only indicate that there was a match on address. On declines, Lithic will return that the AVS was not validated.

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

Point of Sale	Description
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`, `UNKNOWN`.
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`, `UNKNOWN`.
entry_mode.cardholder	Cardholder Presence status, see Cardholder Presence 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.

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
UNKNOWN
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 (includes tap-to-pay, digital wallets, and other methods which implement EMV standard)
`CREDENTIAL_ON_FILE`	Credential on file
`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`	Unspecified method of entry
`UNKNOWN`	Unknown or unmapped method of entry

Cardholder Presence Status

Cardholder presence status	Description
`DEFERRED_BILLING`	Deferred billing payment
`ELECTRONIC_ORDER`	Cardholder not present; electronic order (e.g., via home PC, Internet, mobile phone, PDA)
`INSTALLMENT`	Installment payment
`MAIL_ORDER`	Cardholder not present; mail or facsimile order
`NOT_PRESENT`	Cardholder not present; unspecified
`PRESENT`	Cardholder present
`REOCCURRING`	Standing order or recurring transaction
`TELEPHONE_ORDER`	Cardholder not present; phone or Automated Response Unit (ARU) order
`UNKNOWN`	Unknown or unmapped cardholder presence status

ASA Response Result

Decline reason	Description
AVS_INVALID	Prevent acquirers from approving the transaction despite incorrect AVS. Note: AVS response is not required for this decline type.
INSUFFICIENT_FUNDS	User has insufficient funds. Acquirers may retry the transaction at a later time.
DRIVER_NUMBER_INVALID	The Driver ID given does not match the expected Driver ID for the card. Applicable only for fleet cards.
VEHICLE_NUMBER_INVALID	The Vehicle ID given does not match the expected Vehicle ID for the card. Applicable only for fleet cards.
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.
CARD_PAUSED	When a customer or card program deems that a card should be paused, use the Update Card endpoint to set the card `state` to `PAUSED`. If a merchant sends an authorization request for a paused card, this authorization will be automatically declined by Lithic. This ASA response should only be used when a card program maintains a more granular card state than what is supported via the Update Card endpoint. All other programs should update the card state to address card pauses.

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.

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. Secret keys are configured on a per-program basis, so if you have multiple programs, you must create a key for each program. 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 Responder Endpoint endpoint.

ASA Retry Policy

If Lithic's first attempt to send the ASA request fails due to network connectivity issues or an HTTP status code in the 5xx range, we will immediately retry sending the request. Please be aware that in rare cases, such as when a connection is interrupted while receiving a response, this means that your ASA responder may receive the same request twice. We will not retry on 4xx HTTP errors or on successful responses (2xx status code) with invalid content. Note that this retry policy is different from Events delivery, where Lithic does not need an immediate response.