Service a loan

Operate an active loan account — read its schedule and transactions, record and preview repayments, prepay, reschedule, and correct with reversals.

Once a loan is disbursed it becomes a loan account — the servicing view of the live contract. Servicing is everything that happens across its life: money comes in, the schedule changes, and mistakes get corrected without ever rewriting history.

Read the account

---

Operation	Purpose
GET /api/v1/loan-accounts/{id}	Read the active loan account.
GET /api/v1/loan-accounts/{id}/schedule	Read the current installment schedule.
GET /api/v1/loan-accounts/{id}/transactions	List transactions posted against the account.
GET /api/v1/loan-accounts/{id}/charges	List active charges on the account.
GET /api/v1/loan-accounts/{id}/audit-events	Read the immutable of lifecycle events.

Record money

---

1. Preview the allocation

   POST /api/v1/loan-accounts/{id}/preview-repayment shows how a repayment would be allocated across outstanding installments without recording it. Lender pays the oldest due installment first. Inside each installment it pays penalties, then fees, then interest, then principal.

2. Record the repayment

   POST /api/v1/loan-accounts/{id}/repayments records money received and allocates it across the schedule. Send a request id in X-Request-ID, or in X-Idempotency as the fallback — a call with neither answers 422. The same id with the same loan account, amount, and effective date returns the repayment already recorded. The same id with different facts answers 409. See Idempotency.

3. Prepay

   POST /api/v1/loan-accounts/{id}/prepayments settles the loan ahead of schedule, in whole or in part. A Brazilian loan account needs a prepayment quote first.

Change the schedule

---

POST /api/v1/loan-accounts/{id}/reschedules rewrites the remaining schedule — for a renegotiation, for example. The change is a new schedule state, not an edit of the old one.

Correct without destroying

---

Corrections preserve a consistent, auditable timeline. To undo a recorded transaction, reverse it:

POST /api/v1/loan-accounts/{id}/transactions/{transactionId}/reverse

A reversal appends a compensating transaction rather than deleting anything, so the account keeps a complete audit trail.

A reversal takes a request id on the same headers as a repayment. The same id replays the reversal already recorded only when every reversal fact matches too: the transaction being reversed, the loan account, the reversal effective date, the reason, the profile version, and the jurisdiction code. Any difference in those facts answers 409.

Servicing never edits the past. Repayments, reschedules, and reversals all append new facts. The current state is re-derived from that history, so the account stays explainable from its own record.

What happens downstream

---

When streaming is enabled and a broker is configured, servicing emits repayment.recorded, repayment_reversal.recorded, loan_schedule.prepayment_applied, and loan_schedule.rescheduled. A prepayment settled against a Brazilian prepayment quote records a durable posting intent and relays it to the ledger only when the ledger relay is configured. Read the posting path.

Next steps

---

Accounting and accrual runs

Recognize interest over time and read the journal reference each run records.

Brazil regulatory pack

Read the PDD stage of an overdue loan and apply a stage transition.