Auth Stream Access (ASA) Python Example Application

Table of Contents

• Overview
• Pre-requisites
• Running locally
• Deploy
• Application Logs
• Cleanup
• Scripts
  • Enroll your endpoint in ASA
  • Simulate Events
    • Authorize and Returns
    • Clearing and Void
    • Listing Transactions
  • Create a Card
• Testing

Overview

This is a sample application for creating an auth stream access webhook with AWS API Gateway and Lambda, managed via AWS Serverless Application Model (SAM).

By default, the endpoint is configured to authorize all transactions except those where the merchant is registered in the state of Connecticut (CT), or in which the merchants' category code is "5933" or "5945". These were randomly selected to demonstrate a "deny" workflow. If you wish to modify the behavior, edit the files webhook/app.py and webhook/authorization.py to your needs.

Pre-requisites

• This repository uses Python, and requires that you use Python 3.6+. The Lambda uses a runtime of Python 3.9.
• You must have the AWS CLI and AWS SAM CLI installed.
• Configure your local AWS environment (run aws configure).
• Make sure you have a Sandbox API Key. You can get your API Key by navigating to your account page. After enabling the API, you will have access to both a production and sandbox API key. Be sure to use the Sandbox key for this demo. For more information, please refer to our documentation.

Running locally

To start the API locally run the following command:

sam local start-api

The API will start on port 3000. You can perform an authorized request against the local API as follows:

curl -XPOST http://localhost:3000/webhook -d '{"token": "abcdefgh", "merchant": {"state": "NY", "mcc": "5922"}}'

In this example, the lambda will respond with an "authorize" response and echo the token in the response.

Deploy

To deploy the application, run the following commands:

sam build
sam deploy --guided

Once complete, your new API endpoint will be output to your terminal.

If you make any modifications to the lambda or the template, re-run these two commands to re-deploy your application.

Application Logs

Once deployed, you can fetch logs with the following command:

sam logs -n ASAWebhookFunction --stack-name lithic-asa-demo-python --tail

Cleanup

To delete the sample application that you created, run the following:

aws cloudformation delete-stack --stack-name lithic-asa-demo-python

Scripts

This respository includes some scripts for interacting with the Lithic Sandbox API. Before running these scripts, set up a virtual environment and install local requirements:

python3 -m venv .venv
source .venv/bin/activate
pip3 install -r requirements.local.txt

It may be helpful to store your Lithic Sandbox API key in your ~/.bashrc or equivalent so that you do not need to include it in each script command:

echo 'export LITHIC_SANDBOX_KEY={your_key} >> ~/.bashrc`

Alternatively, if you do not have the Sandbox API Key set as an environment variable, the scripts will prompt you to enter one when run.

Enroll your endpoint in ASA

Using the API Gateway endpoint URL (this URL is output to the terminal after you run the deploy), run the following script to enroll in ASA:

python3 scripts/enroll.py {your_api_endpoint}

If you need to change the enrolled endpoint, disenroll before re-enrolling your new endpoint:

python3 scripts/disenroll.py

Simulate Events

This repository provides a script for simulating any of the following events:

• authorize
• return
• clearing
• void

To do so, run the following script:

python3 scripts/simulate.py {action}

Depending on which action you are simulating, different arguments are required. See below for additional details.

Authorize and Returns

• required pan: A valid PAN; if you need to quickly create a card for testing, see the "Create a Card" script below.
• amount: An amount (in cents) to authorize or return. Defaults to 0.
• descriptor: Merchant descriptor. Defaults to "Sample descriptor".

Example request:

python3 scripts/simulate.py authorize --pan 4111111289144142 --amount 52 --descriptor 'coffee shop'

Clearing and Void

• required token: a transaction token returned from an authorize response.
• amount: Amount (in cents) to clear or void. Typically this will match the original authorization, but may be more or less. If no amount is supplied, the amount of the transaction will be cleared or voided. Any transaction that has any amount completed at all do not have access to this behavior.

Example request:

python3 scripts/simulate.py clearing --token {uuid} --amount 20

Listing Transactions

Now that you've processed a bunch of transactions, you can list them with:

python3 scripts/transactions.py

Given this can produce a lengthy list of transactions, it may be helpful to pipe the output to jq:

python3 scripts/transactions.py | jq

Create a Card

If you need to create a card for testing, you can use the following script:

python3 scripts/create_card.py

This creates an unlocked card in an open state that can be used for testing.

Testing

This demo application includes unit tests for testing the endpoint and authorization logic. To run the test suite, from within your virtual environment, install the test dependencies:

pip3 install -r tests/requirements.txt

Once installed, you can run the tests with pytest:

pytest tests/