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

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,
  "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{}
  }
}

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
}

Merchant Schema

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

Fleet Info

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

User Response

{
  "result": String,
  "token": String,
  "avs_result": String,
  "balance": {
      "amount": Integer,
      "available": Integer
  }
}

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

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

Cardholder Presence Status

ASA Response Result

AVS Response Result

Wallet Type

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.