Skip to main content
This tutorial provides a step-by-step guide to building a simple loan management system using Blnk Finance. You’ll learn how to:
  1. Disburse loans to customers.
  2. Calculate and apply interest.
  3. Process repayments.
  4. Monitor loan status effectively.
For this tutorial, we’ll use the Blnk TypeScript SDK and Blnk Go SDK for the implementation. If you prefer, you can also refer to the API reference for details on the available endpoints.

​
Designing your map

Before writing code, it’s crucial to design a money movement map that outlines how money moves in your system. This serves as the blueprint for your implementation. Lending map Explore the map yourself here This map shows three key aspects our lending fund flow:
  • The Customer Loan Wallet tracks the amount owed by the customer. All loans disbursed to the customer are debited from their loan wallet. A zero balance indicates that all debt has been fully repaid.
  • The @InterestRevenue records all interest earned from loan customers.

​
Prerequisites

Before starting, ensure you have:
  1. A running Blnk Core instance (e.g. at http://localhost:5001).
  2. An API key for Blnk (replace YOUR_API_KEY in the code examples). Required for authenticated requests.
  3. Optionally, you can connect your Blnk Core to your Blnk Cloud workspace to view your ledger data.
To prepare for the rest of this tutorial, read our Building a Wallet with Blnk tutorial if you haven’t already.

​
Initialise your client

Initialize the Blnk client once at the start of your application: 
const { BlnkInit } = require('@blnkfinance/blnk-typescript');

let blnkInstance = null;

async function getBlnkInstance() {
  if (!blnkInstance) {
    blnkInstance = await BlnkInit('', { baseUrl: 'http://localhost:5001' });
  }
  return blnkInstance;
}

​
Create your ledgers

First, we create 2 ledgers.
  • Customer Accounts to organize all customers’ main accounts.
  • Loan Accounts to organize all loan accounts.
# Create main wallet ledger (Customer Accounts)
curl --request POST \
  --url http://localhost:5001/ledgers \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Customer Accounts", 
  "meta_data": {
    "description": "Contains all customer main balances"
  }
}'

# Create loan wallet ledger (Loan Accounts)
curl --request POST \
  --url http://localhost:5001/ledgers \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
  "name": "Loan Accounts", 
  "meta_data": {
    "description": "Contains all customer loan balances"
  }
}'

​
Create customer balances

First, we create the customer’s balance: 
curl --request POST \
  --url http://localhost:5001/balances \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "ledger_id": "ldg_CUSTOMER_LEDGER_ID",
    "currency": "USD",
    "meta_data": {
        "customer_id": "12345",
        "customer_name": "John Doe",
        "account_type": "main",
        "account_status": "active"
    }
  }'
Next, we create the loan balance: 
curl --request POST \
  --url http://localhost:5001/balances \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "ledger_id": "ldg_LOAN_LEDGER_ID",
    "currency": "USD",
    "meta_data": {
        "customer_id": "12345",
        "customer_name": "John Doe"
    }
  }'

​
Disbursing a loan

When the loan is disbursed, money is deducted from the Loan Balance to the Main Balance.
Example scenario
* Starting Scenario
Alice Loan Balance: 0.00 USD
Alice Main Balance: 0.00 USD

* Loan Request Scenario:
Alice borrows 500.00 USD

* After Loan Disbursement:
Alice Loan Balance: - 500.00 USD (debt owed)
Alice Main Balance: + 500.00 USD (funds received by customer)
Initiate this transaction in your ledger: 
curl --request POST \
  --url http://localhost:5001/transactions \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 500,
    "precision": 100,
    "reference": "LOAN-DISBURSE-1709741652384",
    "currency": "USD",
    "source": "bln_LOAN_BALANCE_ID",
    "destination": "bln_CUSTOMER_BALANCE_ID",
    "description": "Loan disbursement",
    "allow_overdraft": true,
    "meta_data": {
        "transaction_type": "loan_disbursement"
    }
  }'

​
Calculate and charge daily interest

Next, we need to calculate daily interest based on the formula P∗R∗TP * R * T, where:
  • P is the principal (loan amount or remaining balance)
  • R is the daily interest rate
  • T is time (1 day for daily interest)
According to our map, interest is transferred from the Loan Balance to the @InterestRevenue.
Example scenario (cont'd)
* After 1 day, with 1% daily interest
+5 USD added to @InterestRevenue
-5 USD deducted from Loan Balance

* Final Balances
Alice Loan Balance: - 505.00 USD (debt owed, including interest)
Alice Main Balance: 500.00 USD (funds received by customer)
@InterestRevenue: + 5.00 USD (interest earned)
Record the daily interest charge on the loan balance: 
curl --request POST \
  --url http://localhost:5001/transactions \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 5,
    "precision": 100,
    "reference": "INTEREST-1709741780214",
    "currency": "USD",
    "source": "bln_LOAN_BALANCE_ID",
    "destination": "@InterestRevenue",
    "description": "Daily interest charge",
    "allow_overdraft": true,
    "meta_data": {
        "transaction_type": "interest_charge",
        "interest_rate": 0.01,
        "principal_amount": 500
    }
  }'

​
Loan repayments

When a customer makes a loan repayment, the money moves from their main balance to the loan balance. 
curl --request POST \
  --url http://localhost:5001/transactions \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 200,
    "precision": 100,
    "reference": "LOAN-REPAY-1709741952867",
    "currency": "USD",
    "source": "bln_CUSTOMER_BALANCE_ID",
    "destination": "bln_LOAN_BALANCE_ID",
    "description": "Loan repayment",
    "meta_data": {
        "transaction_type": "loan_repayment",
        "payment_method": "bank_transfer"
    }
  }'

​
Check loan status

We can check if a loan is fully repaid by verifying if the loan balance is zero or positive: 
curl --request GET \
  --url http://localhost:5001/balances/bln_LOAN_BALANCE_ID \
  --header 'X-blnk-key: <api-key>' \
  --header 'Content-Type: application/json'

​
Conclusion

You now have a fully functional loan management system built with Blnk Finance. This system can:
  • Create and manage loan accounts
  • Disburse loans
  • Calculate and charge daily interest
  • Process loan repayments
  • Track loan status
You can also:
  1. Track due dates: Enhance the loan metadata to include payment schedules and due dates to monitor late payments.
  2. Audit trail: Use detailed metadata for all transactions to maintain a comprehensive audit trail.
  3. Schedule interest charges: Set up a cron job or scheduled task to automatically calculate and charge interest daily.