Auth Stream Access (ASA)

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 request during authorization. The request body includes transaction metadata — amounts, merchant details, card information, and other signals useful for decisioning. Your endpoint should respond with HTTP status 200 and the approval decision in the response body. Lithic converts this response back into ISO-8583 format and forwards it to the network.

🚧

Pre-ASA Request Checks

Before sending the ASA request to your endpoint, Lithic performs a set of pre-authorization checks including default security rules, Authorization Rules, and balance checks for programs using authorization from balance. If any of these checks fail, the transaction is declined and your ASA endpoint will not receive a request. In those cases, the result and detailed_result fields on the Transaction object will provide details about the decision.

Set up ASA in 10 minutes

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

1. NodeJS example
2. Python example

In both sandbox and production, users can configure their ASA endpoint using the enroll and disenroll responder endpoint APIs.

Understanding the ASA Request

📘

This guide focuses on ASA concepts, implementation patterns, and best practices. For the complete, up-to-date API schema including all fields, types, and enumeration values, see ASA Request Schema in our API reference.

The ASA request contains several key data groups that you'll use for decisioning. Each group provides specific information needed to make intelligent authorization decisions.

Transaction Details

Core payment information including:

• Amounts - The amounts object provides structured cardholder, merchant, and hold amounts with their respective currencies. The cardholder amount includes a conversion rate for international transactions. For programs with hold adjustments (e.g., fuel or tipping), the hold amount may exceed the cardholder and merchant amounts.
• Fees and cash back - Acquirer fees and any cash back amount requested by the cardholder
• Risk scoring - Network-provided risk scores on a 0-999 scale
• Transaction type - Whether it's a purchase, balance inquiry, credit, or financial authorization

Merchant & Point of Sale

Identifies where and how the transaction is occurring:

• Merchant identifiers - Acceptor ID and acquiring institution ID that identify specific merchant locations
• MCC - Merchant Category Code for implementing category-based controls
• Merchant descriptor - The name that appears on cardholder statements
• Location details - City, state, country, postal code, and street address. Data quality varies; online merchants may send URLs or phone numbers in the city field, for example
• Service location - Where the cardholder received the service, when different from the card acceptor location. Nullable, only populated when available from the card network
• Entry mode - How card data was captured (e.g., chip, swipe, contactless)
• Presence indicators - Whether card and cardholder were present at the transaction
• Terminal details - Terminal capabilities, type, and whether it's attended
• PIN entry - Whether the cardholder entered their PIN
• Fleet data - For fleet card programs: driver and vehicle numbers for validation, restriction codes (e.g., fuel-only), and prompt codes

Card Data

• Identifiers - Card token (UUID) and last four digits for identification
• Status - Current card state
• Card type - Whether virtual, physical
• Memo - Customizable field for your reference

Authentication Data

Security context for 3DS and tokenized transactions:

• Liability shift - What, if anything, caused fraud liability to move to the issuer (e.g., 3DS_AUTHENTICATED or TOKEN_AUTHENTICATED)
• Authentication outcome - Result of 3DS authentication attempt
• Decision source - Who made the authentication decision
• Linking token - Token that connects the authorization to its 3DS authentication event

Additional Context

Supplementary information that may be included:

• Token details - Wallet type for digital payments (e.g., Apple Pay, Google Pay, Samsung Pay)
• Network-specific data - Additional fields from Mastercard or Visa for advanced decisioning
• AVS data - Address and ZIP code when provided by merchant for verification, along with Lithic's address-on-file match result indicating whether the data matches account holder information

Understanding the ASA Response

📘

For the complete response schema including all fields and enumeration values, see the ASA Response Schema in our API reference.

Your endpoint must return a response indicating your authorization decision. The only required field is result.

Result Values (result)

Any result other than APPROVED or CHALLENGE will decline the transaction — choose the most specific reason to provide the best experience for merchants and cardholders.

AVS Matching (avs_result)

Address verification (AVS) checks the postal code and billing street address. Responding with AVS is optional — if your response omits an AVS result, Lithic can either validate AVS data against account holder information on file, or treat it as matching if it is present in the request, depending on your program configuration. On declines, Lithic will return that AVS was not validated.

If AVS attributes aren't included in the authorization, any AVS response result will be ignored.

AVS Response Values:

• MATCH - Both address and ZIP match your records
• MATCH_ZIP_ONLY - ZIP matches but address doesn't
• MATCH_ADDRESS_ONLY - Address matches but ZIP doesn't
• FAIL - Neither address nor ZIP match

Partial Approval (approved_amount)

To partially approve a transaction, return APPROVED with approved_amount set to the amount you want to authorize (in cents). The terminal must support partial approvals for this to take effect. For more details, see Partial Approval.

Balance Inquiry (balance)

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, calculated as the settled amount minus any pending authorizations

If no balance is returned, Lithic will return $0 to the network.

Operational Considerations

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.

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.

Lithic does not provide a static list of IP addresses that ASA requests are sent from. Webhook signature verification is the supported method for validating request authenticity. If your security requirements call for additional validation beyond webhook signatures, please contact support.

Availability & Retries

Operating an ASA endpoint is a significant infrastructure commitment — your endpoint is in the critical path of every card transaction, and any downtime directly impacts cardholders. If your authorization logic can be expressed via Custom Code Authorization Rules, we recommend doing that instead. Authorization Rules run on Lithic's infrastructure and are designed for five nines of availability. If ASA is the right fit for your program, here are best practices for operating a highly available endpoint:

• Redundancy — Avoid single points of failure. Multi-AZ deployment is the minimum. For more on how we think about availability for authorization infrastructure, see Architecting a Modern Card Authorization Platform.
• Dependency management — Consider whether each external dependencies in your decisioning path are truly necessary. If a dependency is unavailable, is declining the transaction the best outcome for your cardholders? Retry internal operations on transient failures.
• Deployment process — Most outages are caused by bad deploys. Use canary deployments and shift traffic gradually to minimize blast radius.

Lithic's retry behavior: 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 the request. In rare cases, such as when a connection is interrupted while receiving a response, your endpoint may receive the same request twice. We will not retry on 4xx errors or on successful responses (2xx) with invalid content. This retry policy is different from Events delivery, where Lithic does not need an immediate response.