Reference
Loans
Loan accounts with disbursement and repayment tracking. GL posts automatically.
The loans module tracks money borrowed or lent. Principal disburses on creation (or a separate disbursement event), and each repayment splits into principal and interest with the right GL posting.
List loans
GET
/v1/loansReturns all loans on the books.
Query parameters
| Field | Type | Required | Notes |
|---|---|---|---|
businessId | string | yes | |
status | string | no | active, closed, defaulted. |
limit | integer | no | Default 50, max 100. |
Response — 200
{
"success": true,
"data": {
"loans": [
{
"id": "loan_abc",
"loanNumber": "LOAN-2026-001",
"counterparty": "First Bank",
"direction": "borrowed",
"principalKobo": 500_000_000,
"interestRate": 18,
"interestType": "reducing_balance",
"termMonths": 24,
"startDate": "2026-01-01T00:00:00.000Z",
"endDate": "2028-01-01T00:00:00.000Z",
"outstandingKobo": 425_000_000,
"status": "active",
"createdAt": "2026-01-01T09:00:00.000Z"
}
],
"count": 1
}
}Get a single loan
GET
/v1/loans/{id}Fetches one loan with amortization summary.
Create a loan
POST
/v1/loansRecords a loan. Disbursement JE posts on status `active`.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
counterparty | string | yes | Lender name or borrower name. |
direction | string | yes | borrowed or lent. |
principal | number | yes | Naira. |
interestRate | number | yes | Annual percentage. |
interestType | string | no | flat or reducing_balance. Defaults to reducing_balance. |
termMonths | integer | yes | Loan term in months. |
startDate | ISO 8601 | yes | |
disburseOnCreate | boolean | no | If true, sets status to active and posts the disbursement JE. Defaults to true. |
notes | string | no |
Record a repayment
POST
/v1/loans/{id}/repaymentsRecords a loan repayment. Splits into principal and interest and posts the JE.
Body
| Field | Type | Required | Notes |
|---|---|---|---|
amount | number | yes | Total repayment in naira. |
principalAmount | number | no | Override the computed split. |
interestAmount | number | no | Override the computed split. |
paymentDate | ISO 8601 | no | Defaults to today. |
paymentMethod | string | no | Same list as other payment-taking endpoints. |
reference | string | no |
If you omit principalAmount and interestAmount, the API splits the
payment using the loan's schedule.
Related endpoints
- Journal Entries — inspect the disbursement and repayment entries
Reference index
Back to all modules