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:
The loan object
string
Unique loan identifier.
string
string
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.string
The customer this loan belongs to.
string
string
The product template this loan was created from. See
Loan products.
string
string
Lifecycle status. Common values:
Submitted and pending approval,
Approved, Active, Closed (obligations met),
Closed (written off).number
Requested principal amount.
number
Approved principal (may differ from requested). Present after approval.
string
ISO-4217 currency code, e.g.
TZS, USD.integer
Loan term in units of frequency type.
integer
How many installments the loan is scheduled across.
number
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.
number
Principal amount actually paid out at disbursal.
number
Principal portion already repaid.
number
Principal portion still owed.
number
Total interest accrued over the life of the loan.
number
Interest already repaid.
number
Interest still owed.
number
Total fees charged.
number
Fees already paid.
number
Fees still owed.
number
Total penalty charges applied (e.g. late fees).
number
Penalty portion already paid.
number
Penalty portion still owed.
number
Sum of everything the customer has paid in across all components
(principal + interest + fees + penalty).
number
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.
number
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
string
ISO-8601 (
yyyy-MM-dd) date of the next unpaid instalment. Empty
for fully-paid or closed loans.number
Amount outstanding on that next-unpaid instalment (sum of the period’s
outstanding principal + interest + fee + penalty). Zero when there
is no next-due.
boolean
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.array of objects
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.array of objects
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
Read, repayment, undo, delete, and rollback paths all support both
forms; the externalId form is recommended for partner integrations.
For repayment-side operations, see the Repayments
section.