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 length, expressed in units of
termFrequencyType (e.g. 7 with
termFrequencyType "Days" is a 7-day term).string
The unit for
termFrequency — one of "Days", "Weeks", "Months",
"Years". For the current products this is "Days".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 — a repayment
exceeded what was owed. Refunding the credit is an operator action;
contact the integration team.Next-due and schedule
string
ISO-8601 (
yyyy-MM-dd) maturity date of the loan — the date of its
final (for the current single-instalment products, only) instalment.
Omitted for settled loans (Closed, Overpaid). The exact instant is
dueDateTime below.number
What is owed by that date —
totalOutstanding for an Active loan.
Zero when there is no next-due.boolean
true when the loan is Active and its dueDateTime has passed —
the exact instant its penalty fires. Computed server-side so partners
don’t need to compare timestamps 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.string
The exact instant the loan was disbursed, RFC3339 with the EAT
+03:00
offset (e.g. 2026-08-01T13:20:14+03:00). On the create response it is
the instant the disbursal was confirmed; on get and list it is served
from the loan’s penalty schedule, which the platform records within
about fifteen minutes of disbursal — the two agree to the second. A
loan that has been un-disbursed (undo-disbursal, rollback) stops
reporting it.string
The exact instant the loan falls due and its overdue penalty is posted:
disbursedAt plus the product term, to the second — a 7-day loan
disbursed 2026-08-01T13:20:14+03:00 is due 2026-08-08T13:20:14+03:00.
If the loan is still unpaid at that instant the penalty (10% of
principal) is applied within seconds; a repayment that clears the loan
before it attracts no penalty (see Overdue penalty).
Present on create; on get and list once the schedule is recorded (see
disbursedAt) — a read in the first minutes after create, or of a loan
that predates exact-time scheduling, may omit both fields, in which case
overdue falls back to the LMS’s date-based arrears flag. Use it to
drive time-of-day reminders. nextDueDate remains the date-only value.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.
Overdue penalty
Every loan is due atdueDateTime. If it is still Active with
anything outstanding at that instant, the platform posts one overdue
penalty of 10% of the original principal, rounded to whole shillings
(1,000 TZS on a 10,000 loan), within seconds. It is computed on the
principal only — never on interest — and charged once; there is no
daily accrual. Partners do nothing to trigger it. Afterwards
penaltyCharged / penaltyOutstanding and totalOutstanding rise by
the amount, overdue is true, and repayments allocate to the penalty
too (the repayment object shows a penalty
portion).
overdue is the signal to build on, not the calendar date: it flips
exactly at dueDateTime and is always false once the loan is closed.
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.