Step 1 - Enroll a business and their employees

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 business clients, you should first create a Business Account Holder, which will generate an associated account and ISSUING financial account shortly thereafter. Then, you can enroll your business clients' employees as KYC-Exempt Individual Account Holders.

For this guide, assume you are utilizing your own Know Your Business (KYB) process, known as a BYO KYB workflow. For more information on the different KYC and KYB (Know Your Business) processes that Lithic supports, please refer to our guides for Account Holders (Individuals) and Account Holders (Businesses).

Send a POST request to Create Account Holder to create a Business Account Holder:

curl https://api.lithic.com/v1/account_holders
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
   "workflow": "KYB_BYO",
   "tos_timestamp": "2023-01-13T00:00:00Z",
   "business_entity": {
      "legal_business_name": "New Coffee Shop",
      "government_id": "000003333",
      "address": {
          "address1": "456 Main Street",
          "city": "New York",
          "state": "NY",
          "postal_code": "10128",
          "country": "USA"
      },
      "phone_numbers": ["+15555555555"]
   },
   "website_url": "newcoffeeshop.com",
   "kyb_passed_timestamp": "2023-01-14T00:00:00Z",
   "nature_of_business":"Retail store selling coffee and other food items",
   "control_person": {
      "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"
        }
      },
   "beneficial_owner_individuals": [
      {
         "first_name": "Mary",
         "last_name": "AppleSeed",
         "dob": "1991-06-28",
         "phone_number": "+15555555556",
         "email": "[email protected]",
         "government_id": "000004444",
         "address": {
            "address1": "789 Main Street",
            "postal_code": "10128", 
            "city": "New York",
            "state": "NY", 
            "country": "USA"
         }
      }    
   ]
}
'

Below is a sample response:

{
  "account_token": "b68b7424-aa69-4cbc-a946-30d90181b621",
  "status": "ACCEPTED",
  "status_reasons": [],
  "token": "12345678-aa69-4cbc-a946-30d90181b621",
}

At this point, the issuing and operating financial account for the business client is also created. For commercial charge card, only the business client's issuing financial account will be used. You can view this account by sending a GET request to List Financial Accounts:

curl https://api.lithic.com/v1/financial_accounts?account_token=b68b7424-aa69-4cbc-a946-30d90181b621\
  -H "Authorization: YOUR_API_KEY"

Below is a sample response:

{
  "data": [
      {
        "token": "12345678-aa69-4cbc-a946-30d90181b621",
        "created": "2023-06-10T17:48:48Z",
        "updated": "2023-06-10T17:48:48Z",
        "type": "ISSUING",
        "routing_number": "100000000",
        "account_number": "11111234567890"
      },
      {
        "token": "910c80e8-7010-4f46-b16a-8b0b933807ef",
        "created": "2023-06-10T17:48:48Z",
        "updated": "2023-06-10T17:48:48Z",
        "type": "OPERATING",
        "routing_number": "100000000",
        "account_number": "11111234567892"
      }
   ]
}

Next, you will enroll the business's employees and link them to the business using the business_account_token. 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_EXEMPT",
   "kyc_exemption_type": "AUTHORIZED_USER",
   "tos_timestamp": "2023-06-11T00:00:00Z",
   "individual": {
      "first_name": "Johnny",
      "last_name": "AppleSeed",
      "email": "[email protected]",
      "address": {
         "address1": "123 Main Street",
         "postal_code": "10128",
         "city": "New York", 
         "state":"NY",
         "country":"USA"
      }
   },
   business_account_token: "b68b7424-aa69-4cbc-a946-30d90181b621"
}
’

Below is a sample response:

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

Step 2 - Add and Verify an External Bank Account

You will now add the external bank account that your enrolled business clients will use to pay their charge card bills. This should be a commercial bank account that you have received authorization to ACH debit on a recurring basis. The external bank account should be linked to the business's KYB account.

Send a POST request to Create external bank account:

curl https://api.lithic.com/v1/external_bank_accounts \
	-X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
	-d '
{
  "verification_method": "MICRO_DEPOSIT",
  "owner_type": "BUSINESS",
  "owner": "John Doe LLC",
  "type": "CHECKING",
  "routing_number": "021000021",
  "account_number": "123456789",
  "name": "Funding Account",
  "country": "US",
  "currency": "USD"
  "account_token": "b68b7424-aa69-4cbc-a946-30d90181b621"
}
'

Below is a sample response:

{
    "token": "a036e6b5-fd0f-49b2-b0c0-45d84214b189",
    "type": "CHECKING",
    "verification_method": "MICRO_DEPOSIT",
    "owner_type": "BUSINESS",
    "owner": "John Doe LLC",
    "state": "ENABLED",
    "verification_state": "PENDING",
    "routing_number": "021000021",
    "last_four": "6789",
    "name": "John Doe Payables",
    "currency": "USD",
    "country": "US",
    "account_token": "b68b7424-aa69-4cbc-a946-30d90181b621",
    "created": "2023-06-23T20:01:53Z",
    "company_id": null,

Because the External Bank Account object was created with a verification method of MICRO_DEPOSIT, Lithic will now send two small dollar deposits to the bank account ending in 6789. Your business clients should see these amounts reflected in this bank account and enter those amounts in your application. Then, you should send those entered amounts to Lithic to verify the bank account by sending a POST request to Verify External Bank Account

ℹ️
If you are testing in sandbox, please enter the micro deposit amounts of 19 and 89.

curl https://api.lithic.com/v1/external_bank_accounts/a036e6b5-fd0f-49b2-b0c0-45d84214b189/micro_deposits \
  -H 'AUTHORIZATION: YOUR_API_KEY'
    -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
    -d '
{
  "micro_deposits": ["19", "89"]
}
'

Below is a sample response. Note that the verification_state of the external bank account has switched from PENDING to ENABLED:

{
    "token": "a036e6b5-fd0f-49b2-b0c0-45d84214b189",
    "type": "CHECKING",
    "verification_method": "MICRO_DEPOSIT",
    "owner_type": "BUSINESS",
    "owner": "John Doe LLC",
    "state": "ENABLED",
    "verification_state": "ENABLED",
    "routing_number": "021000021",
    "last_four": "6789",
    "name": "John Doe Payables",
    "currency": "USD",
    "country": "USA",
    "account_token": null,
    "created": "2023-06-23T20:01:53Z",
    "company_id": null
}

Step 3 - Configure your charge card program

You will now configure the terms of your charge card program for the business client you just enrolled. With Lithic, you can customize the following configurations for each enrolled business:

Billing Period: number of days between statements
Payment Period: when payment for a statement is due
Credit Limit: maximum amount that a business can borrow for spend across all their employees' cards
External Bank Account: the external bank account that Lithic will auto-collect from when payment is due

For this guide, assume the business will have a billing period of 30 days, a payment period of 5 days, and credit limit of $100,000. Send a POST request to Credit Configuration for the business client's KYB account you just created:

curl https://api.lithic.com/v1/accounts/b68b7424-aa69-4cbc-a946-30d90181b621/credit_configuration
  -X POST \
  -H "Authorization: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '
{
   "billing_period": 30,
   "credit_limit": 10000000,
   "external_bank_account_token": "a036e6b5-fd0f-49b2-b0c0-45d84214b189",
   "payment_period": 5,
}
’

Step 4 - Create a card

Create a card for your business client's employee so that they can spend on their company charge card. All physical and virtual cards created for the employee's KYC-Exempt account will post card transactions against the credit limit of the business. Individual employees do not have their own credit limit. Instead, employee spend can be managed with Lithic's spend limits, Auth Rules, and ASA.

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",
     "account_token": "8dc88f3e-21ea-4d17-9a1c-00cea1a76cf9" ,
}
'

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": "MONTHLY",
  "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 employees 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 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 2023:

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

This should return a response with two results. The first result would be 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":  "2023-06-15T17:48:48Z",
      "token": "99945678-aa69-4cbc-af4p-30d90181b111"
    }
  ],
  "descriptor": "Merchant ABC",
  "created": "2023-06-15T17:48:48Z",
  "updated": "2023-06-15T17:48:48Z"
}

The second 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": "AUTHORIZATION",
      "result": "APPROVED",
      "created":  "2023-06-15T18:48:48Z",
      "token": "11145678-aa69-4cbc-a946-30d90181cccc"
    },
    {
      "amount": -7000,
      "type": "CLEARING",
      "result": "APPROVED",
      "created":  "2023-06-16T17:48:48Z",
      "token": "8d4f88f0-16e9-4755-832e-b09f00c587fc"
    }
  ],
  "descriptor": "Merchant XYZ",
  "created": "2023-06-15T17:48:48Z",
  "updated": "2023-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.

You may also want to check the balance of the business client'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:


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

The available balance of -$90 indicates $90 of the $100K credit limit has been utilized. The total amount of -$70 indicates the total settled amount that would be repaid via auto-collections

Step 6 - Generate Statements

Because this business client is on a 30-day billing period, on July 15th, Lithic will close the billing period and generate the data needed for you to create a statement for the business client.

To retrieve the summary details for statements, send a GET request to List Statements:

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

Below is a sample response:

{
	"ach_period_total": 0,
  "ach_ytd_total": 0,
  "adjustments_period_total": 0,
  "adjustments_ytd_total": 0,
  "amount_due": -7000,
  "available_credit": 9991000,
  "created": "2023-07-15T17:48:48Z",
  "credit_limit": 10000000,
  "days_in_billing_cycle": 30,
  "ending_balance": -7000,
  "financial_account_token": "12345678-aa69-4cbc-a946-30d90181b621",
  "payment_due_date": "2023-07-19",
  "purchases_period_total": -70000,
	"purchases_ytd_total": -70000,
  "starting_balance": 0,
  "statement_end_date": "2023-07-14",
  "statement_start_date": "2023-06-14",
  "token": "81384995-b510-4aef-baaa-66b19dce2848",
	"updated": "2023-07-15T17:48:48Z"
}

Next, let's retrieve the line item details for the statement. Send a GET request to List line items for a statement:

curl https://api.lithic.com/v1/financial_accounts/12345678-aa69-4cbc-a946-30d90181b621/statements/81384995-b510-4aef-baaa-66b19dce2848/line_items \
  -H "Authorization: YOUR_API_KEY"

Below is a sample response:

{
  "amount": -7000,
  "card_token": "7ef7d65c-9023-4da3-b113-3b8583fd7951",
  "category": "CARD",
  "created": "2023-07-15T17:48:48Z",
  "currency": "USD",
  "descriptor": "Merchant XYZ",
  "event_type": "CLEARING", 
  "financial_account_token": "12345678-aa69-4cbc-a946-30d90181b621",
  "financial_transaction_token": "9b8497cb-6ff7-413e-a5a8-a09c906b2b12",
  "settled_date": "2023-06-15",
  "token": "30a0d8ca-c326-4236-b621-2f1d33e19c0e",
}

Step 7 - Auto-Collection of Repayment

Five days later, on July 19th, payment for the $70 bill is due. Lithic auto-initiates an ACH debit origination to collect the $70 from the business client's external bank account. To see this ACH debit origination, you can either query the Payments API or the Financial Transactions API.

You can send a GET request to the Payments API.

curl https://api.lithic.com/v1/payments\
  -H 'AUTHORIZATION: YOUR_API_KEY'

Below is a sample response. Note that the total balance for the business client's issuing financial account has decreased to $0, indicating that they have paid their bill. The available balance remains -$70 until the ACH debit has settled:

{
    "category": "ACH",
    "status": "PENDING",
    "result": "APPROVED",
    "method_attributes": {
        "sec_code": "CCD",
      	"return_reason_code": null,
    },
    "financial_account_token": "12345678-aa69-4cbc-a946-30d90181b621",
    "external_bank_account_token": "a036e6b5-fd0f-49b2-b0c0-45d84214b189",
    "direction": "DEBIT",
    "source": "LITHIC",
    "method": "ACH_NEXT_DAY",
    "token": "656346c4-920c-4d8c-b4d1-41b4fab6c8ab",
    "settled_amount": 0,
    "pending_amount": 7000,
    "currency": "USD",
    "events": [
      	{
            "amount": 7000,
            "type": "ACH_ORIGINATION_PENDING",
            "result": "APPROVED",
            "created": "2023-06-23T22:07:47Z",
            "token": "3de1c04b-59fb-53d3-a3bb-cd436e1c361d"
        },
        {
            "amount": 7000,
            "type": "ACH_ORIGINATION_PROCESSED",
            "result": "APPROVED",
            "created": "2023-06-23T23:07:47Z",
            "token": "3de1c04b-59fb-53d3-a3bb-cd436e1c361d"
        }
    ],
    "descriptor": "CHARGE_COLLECTION",
    "user_defined_id": null,
    "created": "2022-07-19T22:07:47Z",
    "updated": "2022-07-19T23:07:47Z",
    "balance": {
        "financial_account_type": "ISSUING",
        "financial_account_token": "12345678-aa69-4cbc-a946-30d90181b621",
        "currency": "USD",
        "available_amount": -9000,
        "pending_amount": 9000,
        "total_amount": 0,
        "created": "2022-06-10T17:48:48Z",
        "updated": "2022-07-19T23:08:00Z",
        "last_transaction_token": "656346c4-920c-4d8c-b4d1-41b4fab6c8ab",
        "last_transaction_event_token": "3de1c04b-59fb-53d3-a3bb-cd436e1c361d"
    }
}

Once the hold period has passed (default 4 business days), the collected repayment will settle and be automatically swept into your program's operating financial account, where it can be used toward future transactions or repayment to debt providers.

If you send a GET request to the Payments API at this point, you would see the below. Note that the available balance is now $0, indicating that the available credit limit has increased back to $100K:

{
    "category": "ACH",
    "status": "PENDING",
    "result": "APPROVED",
    "method_attributes": {
        "sec_code": "CCD",
      	"return_reason_code": null,
    },
    "financial_account_token": "12345678-aa69-4cbc-a946-30d90181b621",
    "external_bank_account_token": "a036e6b5-fd0f-49b2-b0c0-45d84214b189",
    "direction": "DEBIT",
    "source": "LITHIC",
    "method": "ACH_NEXT_DAY",
    "token": "656346c4-920c-4d8c-b4d1-41b4fab6c8ab",
    "settled_amount": 0,
    "pending_amount": 7000,
    "currency": "USD",
    "events": [
      	{
            "amount": 7000,
            "type": "ACH_ORIGINATION_PENDING",
            "result": "APPROVED",
            "created": "2023-06-23T22:07:47Z",
            "token": "3de1c04b-59fb-53d3-a3bb-cd436e1c361d"
        },
        {
            "amount": 7000,
            "type": "ACH_ORIGINATION_PROCESSED",
            "result": "APPROVED",
            "created": "2023-06-23T23:07:47Z",
            "token": "3de1c04b-59fb-53d3-a3bb-cd436e1c361d"
        },
        {
            "amount": 7000,
            "type": "ACH_ORIGINATION_RELEASED",
            "result": "APPROVED",
            "created": "2023-06-27T22:07:47Z",
            "token": "2a652ffd-cfa2-53c7-997b-26e7ad579995"
        }
    ],
    "descriptor": "CHARGE_COLLECTION",
    "user_defined_id": null,
    "created": "2023-07-19T22:07:47Z",
    "updated": "2023-07-19T23:07:47Z",
    "balance": {
        "financial_account_type": "ISSUING",
        "financial_account_token": "12345678-aa69-4cbc-a946-30d90181b621",
        "currency": "USD",
        "available_amount": 0,
        "pending_amount": 2000,
        "total_amount": 0,
        "created": "2023-06-10T17:48:48Z",
        "updated": "2023-07-19T23:08:00Z",
        "last_transaction_token": "656346c4-920c-4d8c-b4d1-41b4fab6c8ab",
        "last_transaction_event_token": "3de1c04b-59fb-53d3-a3bb-cd436e1c361d"
    }
}