POST /v1/loans submits the application, approves it,
and disburses the full principal, returning a loan that is already
Active.
POST /v1/loans. Reversals are available
for admin/operational use:
| From state | Reversal |
|---|---|
Active | Undo disbursal — returns the loan to Approved |
Approved | Undo approval — returns the loan to Submitted and pending approval |
| Any with outstanding balance | Write off the remaining balance |
The loan object
Unique loan identifier.
Your partner-supplied identifier for the loan. Always present —
an empty string
"" when the loan was created without one — so you
can rely on the key existing when joining list rows back to your own
records.The customer this loan belongs to.
The product template this loan was created from. See
Loan products.
Lifecycle status. Common values:
Submitted and pending approval,
Approved, Active, Closed (obligations met),
Closed (written off).Requested principal amount.
Approved principal (may differ from requested). Present after approval.
ISO-4217 currency code, e.g.
TZS, USD.Loan term in units of frequency type.
How many installments the loan is scheduled across.
Balance roll-up
These fields summarise what has been charged, paid, and is still owed across the loan. Every roll-up field is always present on both list and detail responses — a0 means “nothing charged/owed”, never “field
missing” — so dashboards can read them without existence checks.
Principal amount actually paid out at disbursal.
Principal portion already repaid.
Principal portion still owed.
Total interest accrued over the life of the loan.
Interest already repaid.
Interest still owed.
Total fees charged.
Fees already paid.
Fees still owed.
Total penalty charges applied (e.g. late fees).
Penalty portion already paid.
Penalty portion still owed.
Sum of everything the customer has paid in across all components
(principal + interest + fees + penalty).
Headline “what does the customer still owe” — sum of every
outstanding field above. This is the number to display on the USSD
/ dashboard when telling the customer their debt.
Non-zero only when the loan status is
Overpaid. The credit on the
loan that needs to be refunded via
Credit balance refund.Next-due and schedule
ISO-8601 (
yyyy-MM-dd) date of the next unpaid instalment. Empty
for fully-paid or closed loans.Amount outstanding on that next-unpaid instalment (sum of the period’s
outstanding principal + interest + fee + penalty). Zero when there
is no next-due.
true when the loan is Active and has at least one past-due
unpaid instalment. Computed server-side so partners don’t need to
compare schedule dates against the current date themselves.
Always false for non-Active loans — Closed (obligations met),
Closed (written off), and Overpaid have already settled the
obligation one way or the other.Full amortisation table — one entry per instalment. Each period
carries
period, dueDate, complete, plus the
principal{Due,Paid,Outstanding}, interest{Due,Paid,Outstanding},
fee{Due,Paid,Outstanding}, penalty{Due,Paid,Outstanding}, and
total{Due,Paid,Outstanding} triplets. Always present on single-loan
reads; best-effort on list rows (see the note on
List loans) — a list row can transiently omit
it, in which case nextDueDate/nextDueAmount are still populated.The loan’s repayment transactions, newest first — only customer
repayments (disbursements, waivers, and accruals are excluded). Each
entry is a repayment object. Present only on
single-loan reads, not on the loan list. For a paginated view of the
same data, use List repayments.
Endpoints
| Method | Path | Purpose |
|---|---|---|
| POST | /v1/loans | Create a loan — customerId in the body carries the customer’s externalId; optional loan externalId |
| GET | /v1/loans | List loans — filterable by customerId, customerExternalId, and status |
| GET | /v1/loans/external/{loan_external_id} | Get by externalId (recommended) |
| GET | /v1/loans/{loan_id} | Get by LMS id |
| POST | /v1/loans/external/{loan_external_id}/... | Every repayment op in externalId form (recommended) |
| POST | /v1/loans/{loan_id}/repayments[/...] | Repayments in LMS-id form |
| POST | /v1/loans/external/{loan_external_id}/rollback | Roll back a failed disbursement in one call (recommended) |
| POST | /v1/loans/{loan_id}/rollback | Roll back by LMS id |
| POST | /v1/loans/external/{loan_external_id}/undo-disbursal | Undo disbursal by externalId (recommended) |
| POST | /v1/loans/{loan_id}/undo-disbursal | Undo disbursal by LMS id |
| POST | /v1/loans/external/{loan_external_id}/undo-approval | Undo approval by externalId (recommended) |
| POST | /v1/loans/{loan_id}/undo-approval | Undo approval by LMS id |
| DELETE | /v1/loans/external/{loan_external_id} | Delete by externalId (recommended) |
| DELETE | /v1/loans/{loan_id} | Delete by LMS id |
| POST | /v1/loans/external/{loan_external_id}/adjust-disbursement-date | Adjust disbursement date by externalId (recommended) |
| POST | /v1/loans/{loan_id}/adjust-disbursement-date | Adjust disbursement date by LMS id |
| PUT | /v1/loans/{loan_id} | Update a loan (pending only) — numeric only |
| POST | /v1/loans/{loan_id}/writeoff | Write off — numeric only |