This guide will walk you through a basic program prepay flow using Lithic’s Financial Accounts, Balance, and Financial Transactions endpoints. You will learn how to pre-fund your program and track your balance and financial transactions.

Step 1 - Pre-fund your program

Before you start transacting with cards, you will first fund your program by sending funds via ACH from your bank account to the routing and account number of your program. It will take ~2 business days for the funds to arrive at Lithic, but exact timing will vary depending on your bank’s ACH processing schedules. You do not need to create a Funding Source object at this time.

Send a GET request to List Financial Accounts to retrieve the bank account information for your program:

curl https://api.lithic.com/v1/financial_accounts \
  -H "Authorization: YOUR_API_KEY"

Below is a sample response:

{
  "data": [
      {
        "token": "12345678-aa69-4cbc-a946-30d90181b621",
        "created": "2022-06-10T17:48:48Z",
        "updated": "2022-06-10T17:48:48Z",
        "type": "ISSUING",
        "routing_number": "100000000",
        "account_number": "11111234567890"
      },
      {
        "token": "384hfjnb-aa69-4cbc-a946-30d90181b622",
        "created": "2022-06-10T17:48:48Z",
        "updated": "2022-06-10T17:48:48Z",
        "type": "RESERVE",
        "routing_number": "100000000",
        "account_number": "11111234567891"
      }
   ]
}

You can monitor the status of your ACH funds by checking the balance of your program’s ISSUING financial account using Get Balances:

curl https://api.lithic.com/v1/financial_accounts/12345678-aa69-4cbc-a946-30d90181b621/balances \
  -H "Authorization: YOUR_API_KEY"

Below is a sample response if $200 was successfully received:

{
  "data": [
    {
      "financial_account_type": "ISSUING",
      "financial_account_token": "12345678-aa69-4cbc-a946-30d90181b621",
      "currency": "USD",
      "available_amount": 20000,
      "pending_amount": 0,
      "total_amount": 20000,
      "created": "2022-06-10T17:48:48Z",
      "updated": "2022-06-13T17:48:48Z",
      "last_transaction_token": "9b8497cb-6ff7-413e-a5a8-a09c906b2b12",
      "last_transaction_event_token": "8d4f88f0-16e9-4755-832e-b09f00c587fc"
    }
  ]
}

Step 2 - Add an end-user account

Next, create accounts for your cardholders or end-users. These end-user accounts will not have financial accounts or balances. If you would like to track the balances of your end-user accounts, please ask your Lithic sales rep about [Lithic Send] (https://docs.lithic.com/docs/quick-start-lithic-send).

Let's assume that you are onboarding consumers and will be utilizing your own Know Your Customer (KYC) process. At Lithic, this is known as a BYO KYC workflow. For more information on the different KYC and KYB (Know Your Business) processes that Lithic supports, please refer to the Account Holders (Individuals) and Account Holders (Businesses).

Send a POST request to Create Account Holder:

curl https://api.lithic.com/v1/account_holders
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
   "workflow": "KYC_BYO",
   "tos_timestamp": "2022-06-11T00:00:00Z",
   "individual": {
      "first_name": "Johnny",
      "last_name": "AppleSeed",
      "dob": "1990-06-28",
      "phone_number": "+15555555555",
      "email": "[email protected]",
      "government_id": "000003333",
      "address": {
         "address1": "123 Main Street",
         "postal_code": "10128",
         "city": "New York", 
         "state":"NY",
         "country":"USA"
      }
   }
}
’

Below is a sample response:

{
  "data": {
      "account_token": "8dc88f3e-21ea-4d17-9a1c-00cea1a76cf9",
      "status": "ACCEPTED",
      "status_reasons": [],
      "token": "12345678-aa69-4cbc-a946-30d90181b621"
  }
}

Step 3 - Create a card

Create a card for your end-user accounts so that they can spend their funds. All physical and virtual cards created for an end-user account will fund card transactions using the program's ISSUING balance.

Send a POST request to Create Card to create a virtual card:

curl https://api.lithic.com/v1/cards \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
     "type": "VIRTUAL",
     "memo": "New Card",
     "spend_limit": 1000,
     "spend_limit_duration": "TRANSACTION",
     "state": "OPEN"
}
'

Below is a sample response:

{
  "created": "2021-06-28T22:53:15Z",
  "token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
  "last_four": "4142",
  "hostname": "",
  "memo": "New Card",
  "type": "VIRTUAL",
  "spend_limit": 1000,
  "spend_limit_duration": "TRANSACTION",
  "state": "OPEN",
  "funding": null,
  "auth_rule_tokens": [
     "6397a416-bac6-464c-9647-b006f3a5f91d"
  ],
  "pan": "4111111289144142",
  "cvv": "776",
  "exp_month": "06",
  "exp_year": "2027"
}

Step 4 - Transact

As your end-users transact with their cards, you can view a list of transactions that have occurred with Financial Transactions. A Financial Transaction tells you the state of a transaction as it moves through its lifecycle and transaction events occur.

Let’s take a closer look at Financial Transactions. Assume the following events have occurred:

June 13: $200 ACH credit receipt was received by the program's ISSUING financial account
June 15: $20 was authorized at Merchant ABC
June 15: $70 was authorized at Merchant XYZ
June 16: $70 was cleared at Merchant XYZ (i.e., the transaction’s final amount was $70)

Send a GET request to List Financial Transactions to retrieve all transactions between June 14 and June 16 2022:

curl https://api.lithic.com/v1/financial_accounts/12345678-aa69-4cbc-a946-30d90181b621/financial_transactions?begin=2022-06-14T00%3A00%3A00&end=2022-06-17T00%3A00%3A00 \
  -H "Authorization: YOUR_API_KEY"

This should return a response with three results. Below would be the first result, which represents the $200 pre-payment via ACH debit receipt. Because all ACH receipts are final, the result has a state of SETTLED and the settled_amount is the full $200.

{
  "category": "ACH",
  "status": "SETTLED",
  "result": "APPROVED",
  "token": "257d1c0a-3f9a-471e-95c2-25fc586dc1eb",
  "settled_amount": 20000,  
  "pending_amount": 0,
  "currency": "USD",
  "events": [
    {
      "amount": 20000,
      "type": "ACH_RECEIPT_RELEASED",
      "result": "APPROVED",
      "created":  "2022-06-14T17:48:48Z",
      "token": "8576fyjk-aa69-abcd-a946-30d90181pofb"
    }
  ],
  "descriptor": "Program Prefund",
  "created": "2022-06-14T17:48:48Z",
  "updated": "2022-06-14T17:48:48Z"
}

The second result would represent the $20 authorization at Merchant ABC. It has a state of PENDING and the pending_amount is the full $20. The settled_amount remains at $0 until the transaction has been finalized by the merchant.

{
  "category": "CARD",
  "status": "PENDING",
  "result": "APPROVED",
  "token": "1234fhjt-aa69-4cbc-a946-30d90181dhf7",
  "settled_amount": 0,
  "pending_amount": -2000,
  "currency": "USD",
  "events": [
    {
      "amount": -2000,
      "type": "CARD_AUTHORIZATION",
      "result": "APPROVED",
      "created":  "2022-06-15T17:48:48Z",
      "token": "99945678-aa69-4cbc-af4p-30d90181b111"
    }
  ],
  "descriptor": "Merchant ABC",
  "created": "2022-06-15T17:48:48Z",
  "updated": "2022-06-15T17:48:48Z"
}

The third result represents the $70 cleared transaction at Merchant XYZ. This transaction has an updated state of SETTLED, and the full $70 has been transferred from the pending_amount to the settled_amount.

{
  "category": "CARD",
  "status": "SETTLED",
  "result": "APPROVED",
  "token": "9b8497cb-6ff7-413e-a5a8-a09c906b2b12",
  "pending_amount": 0,
  "settled_amount": -7000,
  "currency": "USD",
  "events": [
    {
      "amount": -7000,
      "type": "CARD_AUTHORIZATION",
      "result": "APPROVED",
      "created":  "2022-06-15T18:48:48Z",
      "token": "11145678-aa69-4cbc-a946-30d90181cccc"
    },
    {
      "amount": -7000,
      "type": "CARD_CLEARING",
      "result": "APPROVED",
      "created":  "2022-06-16T17:48:48Z",
      "token": "8d4f88f0-16e9-4755-832e-b09f00c587fc"
    }
  ],
  "descriptor": "Merchant XYZ",
  "created": "2022-06-15T17:48:48Z",
  "updated": "2022-06-16T17:48:48Z"
}

For more information on the different states of a transaction, please refer to our Financial Transactions guide. For more details on the card transaction lifecycle, please refer to our Transaction Flow guide.

Step 5 - Monitor and Top-up Your Program's Issuing Balances

At the end of the example from Step 5, your program would have a total ISSUING balance of $30, with $20 held in pending to fund the authorized transaction at Merchant ABC. If you retrieved the balance from Get Balances, you would receive the following response:

{
  "data": [
    {
      "financial_account_type": "ISSUING",
      "financial_account_token": "12345678-aa69-4cbc-a946-30d90181b621",
      "currency": "USD",
      "available_amount": 1000,
      "pending_amount": 2000,
      "total_amount": 3000,
      "created": "2022-06-10T17:48:48Z",
      "updated": "2022-06-16T17:48:48Z",
      "last_transaction_token": "9b8497cb-6ff7-413e-a5a8-a09c906b2b12",
      "last_transaction_event_token": "8d4f88f0-16e9-4755-832e-b09f00c587fc"
    }
  ]
}

At this point, if the end-user tries to spend $20 on their card, the transaction would be denied because the available_balance is only $10. If you retrieved from Get Financial Transactions, you would see the following result for the declined transaction:

{
  "category": "CARD",
  "status": "DECLINED",
  "result": "DECLINED",
  "token": "fjcnh586-aa69-4cbc-a946-30d90181pold",
  "pending_amount": 0,
  "settled_amount": 0,
  "currency": "USD",
  "events": [
    {
      "amount": -2000,
      "type": "CARD_AUTHORIZATION",
      "result": "DECLINED",
      "created":  "2022-06-17T17:48:48Z",
      "token": "f2e8e58a-27b5-4bd8-8a23-04c38dcdbf5c"
    }
  ]
  "descriptor": "Merchant 123",
  "created": "2022-06-17T17:48:48Z",
  "updated": "2022-06-17T17:48:48Z"
}

If you have integrated with Lithic’s Transaction webhook, you would see a DECLINED transaction with result code INSUFFICIENT_FUNDS_AFB.