Ledgers tutorial for lending companies to track principal, interest, and fees across loans; surface that data in user balances; enrich transactions with free-form metadata, and more.


Ledgers is an immutable financial database that offers a way for lending companies to:

  • Track principal, interest, fees, capital due to investors, and any other balances in a scalable and flexible ledger;
  • Log transactions in an immutable database with a comprehensive audit log;
  • Deal with high throughput use cases across BNPL, invoice factoring, mortgages, loan servicing, lending marketplaces, crypto lending, embedded lending APIs, and virtually any conceivable lending variant.

In this guide, we will walk through the steps a lending company would take to get started with Ledgers. First, we will create your chart of accounts. Then we’ll work through a sample set of transactions. Finally, we’ll discuss the use of metadata, transaction timing, account categories, and other features that can be helpful to a lending company.

Step 1: Designing your chart of accounts

Ledgers uses double-entry accounting concepts in its design. This ensures scalable consistency. If you are not familiar with debits and credits, read our guide to debits and credits or accounting for developers series.

Modern Treasury customers in lending will often have at least three core groups of accounts:

  1. Accounts related to each loan outstanding such as principal, interest, and fees.
  2. Accounts related to investors or capital providers, such as investor principal balances or interest due to investors.
  3. A set of operating accounts representing revenue, cash, and/or expenses.

This is a basic setup: customers have the flexibility to tailor their set of accounts further depending on their use case.

Loan accounts

These are accounts that track balances for each loan outstanding in your platform.

Account TypeNormalityRepresentsIncreased ByDecreased By
Principal Debit NormalOutstanding principal in a single loan.Disbursement of new loans (debit entry)Borrower paying down principal (credit entry)
Interest Debit NormalInterest balance in a single loan.Interest calculation (debit entry)Borrower paying down interest (credit entry)
Fees Debit NormalFees balance in a single loan.New fees added to a loan (debit entry)Borrower paying fees (credit entry)

These are debit normal accounts because they are akin to receivables - which are assets or uses of funds. Note that your platform would add a set of principal, interest, and fee accounts for each loan. The individual accounts would be represented as Principal Balance - Loan #028374 or a similar description. You can also use metadata to map principal, interest, and fee accounts to a given loan or borrower.

Ledgers will not track interest percentages but will rather log the total balance due in interest. This makes it clean for your application logic to handle changes in interest rates and calculation schedules. The calculation itself happens in your application code, which would read outstanding balances from the ledger and write the resulting interest calculation onto the ledger by way of a modifying entry.

A single payment can affect interest, principal, and fee balances simultaneously. This is implemented in the API by a single ledger transaction being composed of at least two ledger entry objects. For an example of transactions, see Step 3: Defining transaction logic.

This basic setup gives you the flexibility to represent different types of fee or interest structures (such as late or origination fees), all of which would behave as debit normal accounts. The best setup for your business will depend on your use case and desired granularity.

Finally, users can also choose to represent the accounts above on a per-customer basis. However, it is cleaner to represent balances per loan outstanding. Accounts can then be consolidated in hierarchies with account categories.

Liquidity provider accounts

Most lending platforms will choose to track balances associated with liquidity providers. These can also represent individual debt facilities. We typically see two patterns:

Account TypeNormalityRepresentsIncreased ByDecreased By
Investor Principal Credit NormalPrincipal balances associated with a single investor, debt facility or liquidity provider.Capital calls (credit entry)Distributions (debit entry)
Investor Interest Credit NormalInterest due to a single investor, debt facility or liquidity provider.Interest calculation (credit entry)Distributions (debit entry)

This logic can be used regardless of who acts as an investor in your product. If deposits are the source of capital you use for lending, your application will treat such deposits as credit normal accounts. Similar to loan accounts, your platform would have a set of principal and interest balances for each liquidity provider, each represented by a Principal Due - LP #BSE2342 or similar.

Operating accounts

Finally, it is helpful to have a set of accounts representing your product's cash position, revenue, and expenses.

Account TypeNormalityRepresentsIncreased ByDecreased By
CashDebit NormalYour platform's cash balance(s).Cash inflows (debit entry)Cash outflows (credit entry)
RevenueCredit NormalDifferent revenue streams captured in your product or platform.Revenue recognition (credit entry)Adjustments (debit entry)
ExpensesDebit NormalFunds spent in the course of business.Expenses incurred (debit entry)Adjustments (credit entry)

Users will often have many cash balances, such as a cash reserve account that represents funds to be lent out to borrowers. Another example are collection accounts used to receive borrower repayments. If, due to lending requirements, you are keeping multiple types of bank accounts (collections, facility reserves, borrowing base reserves, and so forth), each of them can be represented as an individual ledger account.

It is common for lending users to have a cash omnibus account category that aggregates multiple cash balances. Cash accounts are modified by any kind of cash inflow or outflow and are always debit normal.

Revenue accounts tally up the revenue generated in your lending product. They can be specified by revenue stream, the most common being revenue from fees and revenue from interest. This structure gives you the flexibility to define other revenue accounts, however, all of which would be credit normal. This set of accounts tends to increase as revenue gets recognized and only decrease in the event of adjusting entries.

Finally, expense accounts are the corollary to revenue accounts as they represent any funds your product spends in the course of business, such as:

  • Card processing fees;
  • Origination or servicing fees;
  • Bank and other payment fees;
  • Fees due to 3rd party vendors.

Ledgers is not designed to track all of your business expenses as an accounting software - that happens in your general ledger or ERP system. These expense accounts are meant to track small offsets in transactions happening in real time as transactions get logged into the ledger. In any case, all expense accounts are debit normal as they represent uses of funds.

A sample chart of accounts

A chart of accounts is a useful tool to represent the types of accounts your system will include. Here is a sample chart of accounts for a lender.

AccountNormalityRepresentsSample Metadata
Principal - Loan #203841Debit NormalPrincipal Balance on Loan #203841accountType: loan
loanID: #203841
borrowerID: #AB22212
Interest - Loan #203841Debit NormalInterest Balance on Loan #203841accountType: loan
loanID: #203841
borrowerID: #AB22212
Fees - Loan #203841Debit NormalFees Balance on Loan #203841accountType: loan
loanID: #203841
borrowerID: #AB22212
Principal Due - Liquidity Provider #BSE2342Credit NormalPrincipal due to Liquidity Provider #BSE2342accountType: LP
investorID: #BSE2342
investorCountry: USA
Interest Due - Liquidity Provider #BSE2342Credit NormalInterest due to Liquidity Provider #BSE2342accountType: LP
investorID: #BSE2342
investorCountry: USA
Cash Reserve AccountDebit NormalCash reserved for loan disbursementsaccountType: cash
bankAccountID: BofA#213562345
Collections Cash AccountDebit NormalCash account where borrower repayments will be pooledaccountType: cash
bankAccountID: BofA#562245127
Revenue from InterestCredit NormalOverall revenue from interest spread in the platformaccountType: revenue

Recall that your application will need a set of principal, interest, and fees accounts for each loan in the platform, as well as a set of principal due and interest due for each liquidity provider (investor, deposit holder or debt facility) in the platform. This foundational structure can be used to create new types of accounts as described above.

Modern Treasury Ledgers supports free-form metadata as key-value pairs. Read more about metadata below.

Step 2: Defining transaction logic

The table below shows a handful of transactions that follow the lifecycle of a lending company: acquiring funds from investors, disbursing loans, calculating and recognizing interest, collecting payments from borrowers, and returning capital to investors. In each transaction, we show which accounts get debited or credited.

Note that debit normal accounts are increased by debits and decreased by credits; and that credit normal accounts are increased by credits and decreased by debits. This table starts on day T and increments time in days.

TimeTransactionDebited AccountsCredited AccountsNotes
TInvestor Jane Doe wires capital.Cash (increase)LP Principal Due - Jane Doe #221312 (increase)Capital calls made to liquidity provider increase both our cash account and the balance held on their behalf.
T + 10dNew loan is disbursed to John Smith with ID#13512; interest is recognized concurrently.- Principal - Loan #13512 (increase)

- Interest - Loan #13512 (increase)
- Cash (decrease)

- LP Interest Due - Jane Doe #221312 (increase)

- Revenue from Interest (increase)
As the loan is disbursed we compute both the increase in principal and decrease in cash. Interest due on that loan is also captured. Interest due by the borrower on the loan has to be equal to the interest due to the investor plus our revenue spread. Notice that our revenue will differ from cash, this is borne from using accrual accounting principles and recognizing revenue as an event happens.
T + 40dBorrower John Smith pays installment (n of)Cash (increase)- Principal - Loan #13512 (decrease)

- Interest - Loan #13512 (decrease)
As borrowers pay off installments our cash account increases. Repayments then decrease principal and interest balance due.
4 + 100dInvestor Jane Doe receives disbursement- LP Principal Due - Jane Doe #221312 (decrease)

- LP Interest Due - Jane Doe #221312 (decrease)
Cash (decrease)As cash is disbursed out to liquidity providers we decrease total interest and principal due as well as cash in equal amounts.

Your application code would include logic to handle transactions and appropriately write them into the ledger according to the principles presented above. Our team can help you structure your transaction rules in a way that meets your product requirements and optimizes database performance.

Step 3: Defining metadata, categories, and transaction timing

With your chart of accounts and overall transaction schema mapped out, a few important questions remain.

Ledgers features free-form metadata in the form of key-value pairs in most of our objects. Common metadata fields for lending companies include:

ledgercountryID; productID
ledger accountborrowerID; borrowerZIP; loanID; debt_facilityID
ledger transactionpaymentMethod; transactionType
ledger account categorycategoryType

Ledgers supports querying based on metadata. Any time objects refer to an important concept, it’s helpful to tag them with relevant metadata. By using the list ledger accounts endpoint to query all accounts associated with loan #29273, for instance, the system will return the accounts Interest - #29273, Fees - #29273 and Principal - #29273.

As mentioned before, categories are aggregations at the account level. Categories group multiple accounts. The balance in an account category is equal to the sum of the balances of the accounts within it.

Common categories for lending customers include Principal Outstanding, which aggregates the balance of Principal loan accounts in the ledger, and Investor Interest, which aggregates the sum of each individual investor’s interest balance. Setting up your category map is an important step to ensure the right aggregations are being surfaced to your team. Read more about categories here.

Transaction Timing
Ledgers offers support for multi-state transactions. Transactions in the ledger can have one of the following status values: pending, posted, or archived.

Lending companies might choose to leave transactions at a pending status until a certain condition is met. For instance: a borrower may execute payment in ACH, which only settles after a certain time window. You can choose to represent these balances as pending until transactions are finalized, at which point they would become posted. Once posted, they are immutable.

Each account will have one of three balances: posted (sum of all posted entries), pending (sum of posted and pending entries), and available (sum of all posted entries plus outgoing pending entries).

Furthermore, Ledgers supports back and antedating in the form of an effective_date field on the ledger transaction object. This gives you the flexibility to differentiate between posted dates and effective dates for reporting purposes, as well as include future events in the ledger.

Next Steps

Some of the most successful lending businesses are being built on Ledgers. From here, you can:

  • Review our guide to debits and credits to learn about how debits and credits interact on the platform;
  • Review our guide to Ledgers objects to understand how ledger account objects relate to ledger transactions, ledger entries, and ledger category objects;

Reach out to us at [email protected] if we can be helpful.