Skip to main content
A repayment is a transaction posted against an active loan. The API lets you post a repayment, list a loan’s repayments, and read a single transaction back by id. All repayment endpoints are nested under a loan. The loan can be addressed two equivalent ways. Prefer the externalId form — it lets you drive repayment flows off the reference you already store, with no client-side mapping to a numeric LMS id.

​
Addressing the loan

Both forms hit the same handlers and return identical responses. The externalId form returns 404 not_found if no loan matches.

​
The repayment object

The same object is returned by repay, get a transaction, the transaction list, and as each entry of repaymentHistory on the loan object.
​
string
Unique transaction identifier. Use it on get.
​
string
Transaction type label — always Repayment. The history is restricted to customer repayments; disbursements, waivers, and accruals are excluded.
​
string
ISO-8601 YYYY-MM-DD. Value date the transaction was effective.
​
number
Total transaction amount.
​
number
Portion applied to principal. Omitted if zero.
​
number
Portion applied to interest. Omitted if zero.
​
number
Portion applied to fees. Omitted if zero.
​
number
Portion applied to penalty charges. Omitted if zero.
​
number
Overpayment amount, present only when the transaction exceeded the outstanding balance. A strong signal that something needs reconciling.
​
string
posted for a normal transaction, or reversed if it has been reversed (an operational LMS-side action).

​
Endpoints

The repayment reads (list and get-one) are available in the externalId form only. Posting a repayment still supports both the externalId and numeric-id forms.

​
Repayment history: two ways to read it

The repayment history is available in two places, both returning the object above and both containing only customer repayments (newest first) — disbursements, waivers, and accruals are excluded:
  • Embedded snapshot — every single-loan read (GET /v1/loans/external/{loan_external_id}) includes a repaymentHistory array. Use this for a quick view without a second call. It is not included on the loan list endpoint, only on single-loan reads.
  • Paginated list — GET /v1/loans/external/{loan_external_id}/repayments (reference) returns the same entries with page/rows pagination, for loans with many partial payments.

​
Request body

POST /v1/loans/.../repayments takes:
​
number
required
Must be greater than 0.
​
string
Optional value date (ISO yyyy-MM-dd). Defaults to today. See Reconciling delayed settlements.
​
string
Optional dedupe token — typically your wallet transaction reference (max 100 characters). A repayment carrying a key already seen on the loan returns the original transaction unchanged, so retries never double-post. Strongly recommended on every repayment.
The payment method is filled in by the service.

​
Reconciling delayed settlements

A common integration pattern is to debit the customer’s wallet first, then call this API to settle the loan. If that settle call fails, times out, or is only retried the next day, the payment still happened on your side — and your records are the source of truth for when. Pass transactionDate set to the date the wallet was actually debited. The repayment is then booked as of that value date rather than the day the API call lands. What that does:
  • It records when the payment happened. Allocation and balances reflect the backdated date.
  • It keeps the overdue picture honest. A loan is overdue from 00:00 EAT the day after its dueDate. Booking the payment as of the wallet debit date means a settle call that lands late on your side does not make an on-time customer look late in the LMS.
  • No penalty implications. The current product carries no overdue penalty charge, so a delayed settle call can neither cause nor avoid a penalty — the value date only affects how the payment is dated and allocated (interest → principal).
The loan products use flat interest fixed at disbursement, so the value date never changes the interest owed. The value date must be on/after disbursement and not in the future.