This guide will walk you through a basic disbursement flow using Lithic’s Financial Accounts, Balance, and Financial Transactions endpoints. You will learn how to fund your program, send funds between financial accounts, and track their balances and financial transactions.

Step 1 - Create your end-user financial accounts

When your API key is first provisioned and your program is set up, a default account and your program’s ISSUING, RESERVE, OPERATING financial accounts are created. To add your end-users, you should create account holders, which will generate an associated account and ISSUING financial account shortly thereafter.

For this guide, assume you are utilizing your own Know Your Customer (KYC) process, 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 2 - Fund your program

To fund your program, send funds via ACH from your bank account to the routing and account number of your program's ISSUING financial account only. 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"
      },
      {
        "token": "910c80e8-7010-4f46-b16a-8b0b933807ef",
        "created": "2022-06-10T17:48:48Z",
        "updated": "2022-06-10T17:48:48Z",
        "type": "OPERATING",
        "routing_number": "100000000",
        "account_number": "11111234567892"
      }
   ]
}

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 3 - Disburse funds to your end-users

Once your program’s ISSUING financial account has been funded, you should disburse funds to your end-users’ ISSUING financial accounts with Create Transfer.

First, retrieve the financial account details of your end-user by sending a request to List Financial Accounts. You will need to pass the account_token generated in Step 1 as a query parameter:

curl https://api.lithic.com/v1/financial_accounts?account_token=8dc88f3e-21ea-4d17-9a1c-00cea1a76cf9 \
  -H "Authorization: YOUR_API_KEY"

Below is a sample response:

{
  "data": [
      {
        "token": "87654321-aa69-4cbc-a946-30d90181ccaa",
        "created": "2022-06-11T00:00:00Z",
        "updated": "2022-06-11T00:00:00Z",
        "type": "ISSUING",
        "routing_number": null,
        "account_number": null
      },
      {
        "token": "ab9a4c1f-8c48-4171-8c29-0df96d678b75",
        "created": "2022-06-11T00:00:00Z",
        "updated": "2022-06-11T00:00:00Z",
        "type": "OPERATING",
        "routing_number": null,
        "account_number": null
      }
   ]
}

Next, send a POST request to Create Transfer:

curl https://api.lithic.com/v1/transfer \
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d ‘
{
    "from": "12345678-aa69-4cbc-a946-30d90181b621",
    "to": "87654321-aa69-4cbc-a946-30d90181ccaa",
    "amount": 10000,
    "memo": "test",
    "transaction_token": "6a885bcb-89f6-4fcb-a0ce-7f0233ae20a0"
}
‘

Below is a sample response:

{
  "token": "6a885bcb-89f6-4fcb-a0ce-7f0233ae20a0",
  "from_balance": {
    "financial_account_type": "ISSUING",
    "financial_account_token": "12345678-aa69-4cbc-a946-30d90181b621",
    "currency": "USD",
    "available_amount": 10000,
    "pending_amount": 0,
    "total_amount": 10000,
    "created": "2022-06-10T17:48:48Z",
    "updated": "2022-06-14T17:48:48Z",
    "last_transaction_token": "6a885bcb-89f6-4fcb-a0ce-7f0233ae20a0",
    "last_transaction_event_token": "a43ba171-0da8-405f-9a4e-b583f36ec967"
  },
  "to_balance": {
    "financial_account_type": "ISSUING",
    "financial_account_token": "87654321-aa69-4cbc-a946-30d90181ccaa",
    "currency": "USD",
    "available_amount": 10000,
    "pending_amount": 0,
    "total_amount": 10000,
    "created": "2022-06-10T17:48:48Z",
    "updated": "2022-06-14T17:48:48Z",
    "last_transaction_token": "48d7a3d0-883d-493f-8029-25e6dfdb044f",
    "last_transaction_event_token": "b7f93ded-87fd-4672-bcd4-c18102c23e31"
  },
  "result": "APPROVED"
}

Step 4 - Create a card

Create a card for your end-users so that they can spend their funds. All physical and virtual cards created for an end-user account will fund card transactions using that account’s ISSUING balance. If you want each card to maintain its own separate ISSUING balance, you will need to create one account holder for each card.

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 5 - 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 with one of your end-users:

June 14: $100 was transferred from the program ISSUING balance
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 $100 transfer between the program and the end-user account. Because all transfers are instant and final, the result has a state of SETTLED and the settled_amount is the full $100.

{
  "category": "TRANSFER",
  "status": "SETTLED",
  "result": "APPROVED",
  "token": "257d1c0a-3f9a-471e-95c2-25fc586dc1eb",
  "settled_amount": 10000,  
  "pending_amount": 0,
  "currency": "USD",
  "events": [
    {
      "amount": 10000,
      "type": "TRANSFER",
      "result": "APPROVED",
      "created":  "2022-06-14T17:48:48Z",
      "token": "8576fyjk-aa69-abcd-a946-30d90181pofb"
    }
  ],
  "descriptor": "test",
  "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 6 - Monitor and Top-up Your End-Users’ Issuing Balances

At the end of the example from Step 5, your end-user would have a total ISSUING balance of $30, with $20 held in pending to fund the authorized transaction at Merchant ABC. If you retrieved this end-user’s ISSUING 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.

To instantly top-up your end-user account, repeat Step 3 and use Create Transfer to instantly disburse funds from your program to your end-user’s ISSUING account.