> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blnkfinance.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Building a Lending Management System
> Learn how to manage & track loans and repayments with the Blnk Ledger.
export const CtaCallout = props => {
const {title, buttonLabel, href, trackingEvent, buttonTarget, rel = "noopener noreferrer", children} = props;
const handleCtaClick = () => {
if (typeof window === "undefined" || !trackingEvent) {
return;
}
try {
window.dispatchEvent(new CustomEvent("blnk:docs-cta", {
detail: {
name: trackingEvent,
href
}
}));
} catch {}
try {
window.posthog?.capture?.(trackingEvent, {
href
});
} catch {}
const gaPayload = {
cta_href: href
};
try {
window.gtag?.("event", trackingEvent, gaPayload);
} catch {}
try {
window.dataLayer = window.dataLayer || [];
window.dataLayer.push({
event: trackingEvent,
...gaPayload
});
} catch {}
};
const isExternal = typeof href === "string" && (/^https?:\/\//i).test(href);
const target = buttonTarget ?? (isExternal ? "_blank" : undefined);
const linkRel = isExternal ? rel : undefined;
return ;
};
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](/sdks/typescript) and [Blnk Go SDK](/sdks/go) for the implementation. If you prefer, you can also refer to the [API reference](/reference/create-ledger) for details on the available endpoints.
***
## Designing your map
Before writing code, it's crucial to design a [money movement map](/ledgers/money-movement-map) that outlines how money moves in your system. This serves as the blueprint for your implementation.
[Explore the map yourself here](https://map.blnkfinance.xyz/9I4HuNl54p)
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](https://cloud.blnkfinance.com/?utm_source=blnk_docs\&utm_medium=documentation\&utm_campaign=tutorials%2Fdigital-banking%2Flending) workspace to view your ledger data.
To prepare for the rest of this tutorial, read our [Building a Wallet with Blnk](/tutorials/quick-start/wallet-management) tutorial if you haven't already.
***
## Create your ledgers
First, we create 2 ledgers.
* `Customer Accounts` to organize all customers' main accounts.
* `Loan Accounts` to organize all loan accounts.
```bash cURL wrap expandable theme={"system"}
# Create main wallet ledger (Customer Accounts)
curl -X POST "http://localhost:5001/ledgers" \
-H "X-blnk-key: " \
-H "Content-Type: application/json" \
-d '{
"name": "Customer Accounts",
"meta_data": {
"description": "Contains all customer main balances"
}
}'
# Create loan wallet ledger (Loan Accounts)
curl -X POST "http://localhost:5001/ledgers" \
-H "X-blnk-key: " \
-H "Content-Type: application/json" \
-d '{
"name": "Loan Accounts",
"meta_data": {
"description": "Contains all customer loan balances"
}
}'
```
```typescript TypeScript wrap expandable theme={"system"}
async function createCustomerLedger() {
const customerLedger = await blnk.Ledgers.create({
name: "Customer Accounts",
meta_data: {
description: "Contains all customer main balances"
}
});
console.log("Customer Ledger created:", customerLedger.data);
return customerLedger.data.ledger_id;
}
async function createLoanLedger() {
const loanLedger = await blnk.Ledgers.create({
name: "Loan Accounts",
meta_data: {
description: "Contains all customer loan balances"
}
});
console.log("Loan Ledger created:", loanLedger.data);
return loanLedger.data.ledger_id;
}
```
```go Go wrap expandable theme={"system"}
func createCustomerLedger() (string, error) {
client := getClient()
ledger, _, err := client.Ledger.Create(blnkgo.CreateLedgerRequest{
Name: "Customer Accounts",
MetaData: map[string]interface{}{
"description": "Contains all customer main balances",
},
})
if err != nil {
return "", err
}
fmt.Println("Customer Ledger created:", ledger.LedgerID)
return ledger.LedgerID, nil
}
func createLoanLedger() (string, error) {
client := getClient()
ledger, _, err := client.Ledger.Create(blnkgo.CreateLedgerRequest{
Name: "Loan Accounts",
MetaData: map[string]interface{}{
"description": "Contains all customer loan balances",
},
})
if err != nil {
return "", err
}
fmt.Println("Loan Ledger created:", ledger.LedgerID)
return ledger.LedgerID, nil
}
```
***
## Create customer balances
First, we create the customer's balance:
```bash cURL wrap theme={"system"}
curl -X POST "http://localhost:5001/balances" \
-H "X-blnk-key: " \
-H "Content-Type: application/json" \
-d '{
"ledger_id": "ldg_CUSTOMER_LEDGER_ID",
"currency": "USD",
"meta_data": {
"customer_id": "12345",
"customer_name": "John Doe",
"account_type": "main",
"account_status": "active"
}
}'
```
```typescript TypeScript wrap expandable theme={"system"}
async function createCustomerMainBalance(customerLedgerId, customerDetails) {
const mainBalance = await blnk.LedgerBalances.create({
ledger_id: customerLedgerId,
currency: "USD",
meta_data: {
customer_id: customerDetails.id,
customer_name: customerDetails.name,
account_type: "main",
account_status: "active"
}
});
console.log("Customer Main Balance created:", mainBalance.data);
return mainBalance.data.balance_id;
}
```
```go Go wrap expandable theme={"system"}
func createCustomerMainBalance(customerLedgerID string, customerDetails CustomerDetails) (string, error) {
client := getClient()
balance, _, err := client.LedgerBalance.Create(blnkgo.CreateLedgerBalanceRequest{
LedgerID: customerLedgerID,
Currency: "USD",
MetaData: map[string]interface{}{
"customer_id": customerDetails.ID,
"customer_name": customerDetails.Name,
"account_type": "main",
"account_status": "active",
},
})
if err != nil {
return "", err
}
fmt.Println("Customer Main Balance created:", balance.BalanceID)
return balance.BalanceID, nil
}
```
Next, we create the loan balance:
```bash cURL wrap theme={"system"}
curl -X POST "http://localhost:5001/balances" \
-H "X-blnk-key: " \
-H "Content-Type: application/json" \
-d '{
"ledger_id": "ldg_LOAN_LEDGER_ID",
"currency": "USD",
"meta_data": {
"customer_id": "12345",
"customer_name": "John Doe"
}
}'
```
```typescript TypeScript wrap expandable theme={"system"}
async function createLoanBalance(loanLedgerId, customerDetails, loanDetails) {
const loanBalance = await blnk.LedgerBalances.create({
ledger_id: loanLedgerId,
currency: "USD",
meta_data: {
customer_id: customerDetails.id,
customer_name: customerDetails.name
}
});
console.log("Loan Balance created:", loanBalance.data);
return loanBalance.data.balance_id;
}
```
```go Go wrap expandable theme={"system"}
func createLoanBalance(loanLedgerID string, customerDetails CustomerDetails) (string, error) {
client := getClient()
balance, _, err := client.LedgerBalance.Create(blnkgo.CreateLedgerBalanceRequest{
LedgerID: loanLedgerID,
Currency: "USD",
MetaData: map[string]interface{}{
"customer_id": customerDetails.ID,
"customer_name": customerDetails.Name,
},
})
if err != nil {
return "", err
}
fmt.Println("Loan Balance created:", balance.BalanceID)
return balance.BalanceID, nil
}
```
***
## Disbursing a loan
When the loan is disbursed, money is deducted from the `Loan Balance` to the `Main Balance`.
```txt Example scenario wrap theme={"system"}
* 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:
```bash cURL wrap expandable theme={"system"}
curl -X POST "http://localhost:5001/transactions" \
-H "X-blnk-key: " \
-H "Content-Type: application/json" \
-d '{
"precise_amount": 50000,
"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"
}
}'
```
```typescript TypeScript wrap expandable theme={"system"}
async function disburseLoan(loanBalanceId, customerBalanceId, loanAmount) {
// Generate a unique reference for this transaction
const reference = `LOAN-DISBURSE-${Date.now()}`;
const disbursement = await blnk.Transactions.create({
precise_amount: loanAmount * 100,
precision: 100,
reference: reference,
currency: "USD",
source: loanBalanceId,
destination: customerBalanceId,
description: "Loan disbursement",
allow_overdraft: true, // This allows the loan balance to go negative
meta_data: {
transaction_type: "loan_disbursement",
}
});
console.log("Loan disbursed:", disbursement.data);
const baseUrl = process.env.BLNK_BASE_URL ?? 'http://localhost:5001';
const apiKey = process.env.BLNK_API_KEY ?? '';
const metaRes = await fetch(`${baseUrl}/${loanBalanceId}/metadata`, {
method: 'POST',
headers: {
'X-Blnk-Key': apiKey,
'Content-Type': 'application/json',
},
body: JSON.stringify({
meta_data: { loan_status: 'active' },
}),
});
if (!metaRes.ok) throw new Error(await metaRes.text());
return disbursement.data.transaction_id;
}
```
```go Go wrap expandable theme={"system"}
func disburseLoan(loanBalanceID, customerBalanceID string, loanAmount float64) (string, error) {
client := getClient()
reference := fmt.Sprintf("LOAN-DISBURSE-%d", time.Now().Unix())
disbursement, _, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
ParentTransaction: blnkgo.ParentTransaction{
PreciseAmount: loanAmount * 100,
Precision: 100,
Reference: reference,
Currency: "USD",
Source: loanBalanceID,
Destination: customerBalanceID,
Description: "Loan disbursement",
MetaData: map[string]interface{}{
"transaction_type": "loan_disbursement",
},
},
AllowOverdraft: true,
})
if err != nil {
return "", err
}
_, _, err = client.Metadata.UpdateMetadata(loanBalanceID, blnkgo.UpdateMetaDataRequest{
MetaData: map[string]interface{}{
"loan_status": "active",
},
})
if err != nil {
return "", err
}
fmt.Println("Loan disbursed:", disbursement.TransactionID)
return disbursement.TransactionID, nil
}
```
***
## Calculate and charge daily interest
Next, we need to calculate daily interest based on the formula $P * 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`.
```txt Example scenario (cont'd) wrap theme={"system"}
* 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:
```bash cURL wrap expandable theme={"system"}
curl -X POST "http://localhost:5001/transactions" \
-H "X-blnk-key: " \
-H "Content-Type: application/json" \
-d '{
"precise_amount": 500,
"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
}
}'
```
```typescript TypeScript wrap expandable theme={"system"}
async function calculateAndChargeInterest(loanBalanceId, interestRate) {
// Get current loan balance
const loanBalance = await blnk.LedgerBalances.get(loanBalanceId);
// Get the principal amount (convert negative balance to positive)
const principal = Math.abs(loanBalance.data.balance);
// Calculate daily interest amount
const dailyRate = interestRate / 365; // Convert annual rate to daily
const interestAmount = principal * dailyRate;
// Round to 2 decimal places and convert to cents
const roundedInterest = Math.round(interestAmount * 100) / 100;
// Generate a unique reference
const reference = `INTEREST-${Date.now()}`;
// Transfer interest from loan balance to interest revenue balance
const interestTransaction = await blnk.Transactions.create({
precise_amount: roundedInterest * 100,
precision: 100,
reference: reference,
currency: "USD",
source: loanBalanceId,
destination: "@InterestRevenue",
description: "Daily interest charge",
allow_overdraft: true, // Allow loan balance to go further negative
meta_data: {
transaction_type: "interest_charge",
interest_rate: interestRate,
principal_amount: principal / 100, // Convert back to dollars for readability
}
});
console.log("Interest charged:", interestTransaction.data);
return interestTransaction.data.transaction_id;
}
```
```go Go wrap expandable theme={"system"}
func calculateAndChargeInterest(loanBalanceID string, interestRate float64) (string, error) {
client := getClient()
loanBalance, _, err := client.LedgerBalance.Get(loanBalanceID)
if err != nil {
return "", err
}
balanceFloat, _ := loanBalance.Balance.Float64()
principal := math.Abs(balanceFloat)
dailyRate := interestRate / 365
interestAmount := principal * dailyRate
roundedInterest := math.Round(interestAmount*100) / 100
reference := fmt.Sprintf("INTEREST-%d", time.Now().Unix())
interestTransaction, _, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
ParentTransaction: blnkgo.ParentTransaction{
PreciseAmount: roundedInterest * 100,
Precision: 100,
Reference: reference,
Currency: "USD",
Source: loanBalanceID,
Destination: "@InterestRevenue",
Description: "Daily interest charge",
MetaData: map[string]interface{}{
"transaction_type": "interest_charge",
"interest_rate": interestRate,
"principal_amount": principal / 100,
},
},
AllowOverdraft: true,
})
if err != nil {
return "", err
}
fmt.Println("Interest charged:", interestTransaction.TransactionID)
return interestTransaction.TransactionID, nil
}
```
***
## Loan repayments
When a customer makes a loan repayment, the money moves from their main balance to the loan balance.
```bash cURL wrap expandable theme={"system"}
curl -X POST "http://localhost:5001/transactions" \
-H "X-blnk-key: " \
-H "Content-Type: application/json" \
-d '{
"precise_amount": 20000,
"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"
}
}'
```
```typescript TypeScript wrap expandable theme={"system"}
async function processLoanRepayment(customerBalanceId, loanBalanceId, repaymentAmount) {
// Generate a unique reference
const reference = `LOAN-REPAY-${Date.now()}`;
// Transfer from customer's balance to loan balance
const repayment = await blnk.Transactions.create({
precise_amount: repaymentAmount * 100,
precision: 100,
reference: reference,
currency: "USD",
source: customerBalanceId,
destination: loanBalanceId,
description: "Loan repayment",
meta_data: {
transaction_type: "loan_repayment",
payment_method: "bank_transfer"
}
});
console.log("Loan repayment processed:", repayment.data);
// Check if loan is fully repaid
const updatedLoanBalance = await blnk.LedgerBalances.get(loanBalanceId);
if (updatedLoanBalance.data.balance >= 0) {
// Loan is fully repaid, update status
const baseUrl = process.env.BLNK_BASE_URL ?? 'http://localhost:5001';
const apiKey = process.env.BLNK_API_KEY ?? '';
const metaRes = await fetch(`${baseUrl}/${loanBalanceId}/metadata`, {
method: 'POST',
headers: {
'X-Blnk-Key': apiKey,
'Content-Type': 'application/json',
},
body: JSON.stringify({
meta_data: {
loan_status: 'fully_repaid',
repayment_completed_date: new Date().toISOString(),
},
}),
});
if (!metaRes.ok) throw new Error(await metaRes.text());
console.log("Loan fully repaid!");
}
return repayment.data.transaction_id;
}
```
```go Go wrap expandable theme={"system"}
func processLoanRepayment(customerBalanceID, loanBalanceID string, repaymentAmount float64) (string, error) {
client := getClient()
reference := fmt.Sprintf("LOAN-REPAY-%d", time.Now().Unix())
repayment, _, err := client.Transaction.Create(blnkgo.CreateTransactionRequest{
ParentTransaction: blnkgo.ParentTransaction{
PreciseAmount: repaymentAmount * 100,
Precision: 100,
Reference: reference,
Currency: "USD",
Source: customerBalanceID,
Destination: loanBalanceID,
Description: "Loan repayment",
MetaData: map[string]interface{}{
"transaction_type": "loan_repayment",
"payment_method": "bank_transfer",
},
},
})
if err != nil {
return "", err
}
updatedLoanBalance, _, err := client.LedgerBalance.Get(loanBalanceID)
if err != nil {
return "", err
}
repaidBalance, _ := updatedLoanBalance.Balance.Float64()
if repaidBalance >= 0 {
_, _, err = client.Metadata.UpdateMetadata(loanBalanceID, blnkgo.UpdateMetaDataRequest{
MetaData: map[string]interface{}{
"loan_status": "fully_repaid",
"repayment_completed_date": time.Now().UTC().Format(time.RFC3339),
},
})
if err != nil {
return "", err
}
fmt.Println("Loan fully repaid!")
}
fmt.Println("Loan repayment processed:", repayment.TransactionID)
return repayment.TransactionID, nil
}
```
***
## Check loan status
We can check if a loan is fully repaid by verifying if the loan balance is zero or positive:
```bash cURL wrap theme={"system"}
curl -X GET "http://localhost:5001/balances/bln_LOAN_BALANCE_ID" \
-H "X-blnk-key: " \
-H "Content-Type: application/json"
```
```typescript TypeScript wrap expandable theme={"system"}
async function checkLoanStatus(loanBalanceId) {
const loanBalance = await blnk.LedgerBalances.get(loanBalanceId);
const status = {
balance_id: loanBalanceId,
current_balance: loanBalance.data.balance / 100, // Convert cents to dollars
is_fully_repaid: loanBalance.data.balance >= 0,
loan_status: loanBalance.data.meta_data.loan_status,
loan_details: loanBalance.data.meta_data
};
console.log("Loan status:", status);
return status;
}
```
```go Go wrap expandable theme={"system"}
func checkLoanStatus(loanBalanceID string) (map[string]interface{}, error) {
client := getClient()
loanBalance, _, err := client.LedgerBalance.Get(loanBalanceID)
if err != nil {
return nil, err
}
balanceFloat, _ := loanBalance.Balance.Float64()
status := map[string]interface{}{
"balance_id": loanBalanceID,
"current_balance": balanceFloat / 100,
"is_fully_repaid": balanceFloat >= 0,
"loan_status": loanBalance.MetaData["loan_status"],
"loan_details": loanBalance.MetaData,
}
fmt.Println("Loan status:", status)
return status, nil
}
```
***
## 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.
***
Get dedicated support for architecture reviews, integration planning, ledger workflows, and production deployment.