Fully Customize Authorizations

Estimated time: ~10 minutes

Lithic's Auth Stream Access (ASA) feature is for customers that need full customization of their authorization logic. With ASA, Lithic forwards transactions to your servers in real-time so that you can approve or decline each transaction.

🚧

Enterprise Feature

Auth Stream Access is an Enterprise feature and only available in the Production environment for Enterprise customers. Enterprise customers must complete an approval process before they can receive ASA messages on their servers.

Please reach out to Lithic if you would like to use this feature.

Note: Auth Stream Access is available in the Sandbox environment for all customers.

📘

Authorization Rules + Auth Stream Access

You can use Authorization Rules and Auth Stream Access together. When Lithic receives a transaction from the card networks, we automatically decline any that fail your Authorization Rules. Lithic forwards the remaining transactions to your servers as Auth Stream Access messages for you to approve or decline.

Enroll in Auth Stream Access

To start using Auth Stream Access, you need to expose an endpoint on your servers for receiving Auth Stream Access messages. For each transaction, Lithic will send an Auth Stream Access message to this endpoint as a POST request.

Once you have exposed the endpoint, you must register the endpoint's URL with Lithic.

Auth Stream Access enrollment will not work in Production until you have completed the approval process

/*
const lithic = new Lithic({
  apiKey: "{Sandbox API key}", // or "Production API key"
  environment: "sandbox", // or "production". Defaults to "production"
});
*/

lithic.authStreamEnrollment.enroll({
  webhook_url: "{Your endpoint URL}"
})

'''
lithic = Lithic(
  api_key="{Sandbox API key}",  # or "Production API key"
  environment="sandbox",  # or "production". Defaults to "production"
)
'''

lithic.auth_stream_enrollment.enroll({
  "webhook_url": "{Your endpoint URL}"
})

curl --request POST \
     --url https://sandbox.lithic.com/v1/auth_stream \
     --header "Accept: application/json" \
     --header "Authorization: {Sandbox API key}" \
     --header "Content-Type: application/json" \
     --data '
{
     "webhook_url": "{Your endpoint URL}"
}
'

Once you enroll your URL, you can test that you are receiving ASA messages by simulating a transaction.

Respond to Auth Stream Access messages

Each Auth Stream Access message will contain information about the transaction, including the transaction amount, merchant, and card. Based on this information, you can decide to approve or decline the transaction.

Each incoming request must be responded to with an Auth Stream Access response object. This object needs to include:

• Result (string): "APPROVED" to accept the transaction. Any other value will decline the transaction.
• Token (string): The Auth Stream Access token in the received POST request.

For more information about Auth Stream Access, check out our in-depth guide: Auth Stream Access

Below is an example of exposing an endpoint on an Express server to receive Auth Stream Access messages:

/* Example Endpoint */

// Your Server
const express = require('express')
const app = express()
app.use(express.json()) // for parsing application/json

// Auth Stream Access endpoint
app.post('/my_auth_stream_access_endpoint', (req, res) => {
    const { body: {token, amount, merchant}} = req;

  	// Custom Approve/Decline Logic ...
    // ... ex. decline if amount is > $500 ...
    // ... ex. approve if merchant code is 'groceries'
    // ... ex. decline if card was created within the last day ...

    const result = 'APPROVED'; // or 'DECLINED', 'UNAUTHORIZED_MERCHANT', etc.
    return res.json({ result, token })
});

If AWS is your cloud provider, Lithic provides a ready-to-deploy lambda function that you can use to quickly spin-up an AWS Serverless Application Model (SAM) to receive and handle Auth Stream Access messages:

NodeJS example: https://github.com/lithic-com/asa-demo-node
Python example: https://github.com/lithic-com/asa-demo-python

Response timeouts

Every transaction request received from the card networks requires an approve or decline response within 7 seconds.

⚠

️ Transactions auto-decline after 7 seconds

If the card networks do not receive a response within 7 seconds, they will automatically decline the transaction.

The 7-second countdown begins as soon as the card networks send the request to Lithic and includes the roundtrip time from the card network to Lithic to your servers and back.

At Lithic we are consistently improving our infrastructure to minimize the amount of time it takes for Auth Stream Access messages to pass through our servers. Still, the sooner you respond to Auth Stream Access messages, the more likely that Lithic can respond to the card networks within the allotted time.