Read the account
Record money
1
Preview the allocation
POST /api/v1/loan-accounts/{id}/preview-repayment shows how Lender would allocate a repayment 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 reversal facts are the transaction you reverse, the loan account, the reversal effective date, the reason, the profile version, and the jurisdiction code. Any difference in those facts answers 409.
A returned final payment becomes a receivable
Reversing the payment that settled a consignado loan does not always give the debt back to the contract. The exclusion order tells the payer entity to stop deducting from payroll. Once the order has gone to the rail and the rail did not reject it, the payroll mandate is gone. Nothing in Lender registers it again. A contract revived there would be debt with no instrument behind it. It would be chased for arrears, provisioned, and offered back to the official as something whose deduction could be cancelled a second time. Lender still accepts the reversal, because the bank returned the money and the ledger has to agree with the bank. What changes is the destination. Lender opens a returned-payment receivable against the borrower, outside the credit operation, with no payroll mandate and collected by other means. The reversal answers with which of the two happened, and with the receivable’s id when one opened. The contract keeps its settled state. Nothing reopens. Lender replays no schedule and undoes no allocation.
An exclusion still in flight counts as issued. A reversal cannot wait for the rail to answer. If a revival happens before the rail answers, nothing undoes it when the answer comes back confirmed. Where the rail rejected the exclusion, the mandate never died, and the reversal revives the contract exactly as it always did.
Working the receivable
A collection settles the whole debt, so it carries no amount: Lender reads the figure from the receivable. It takes a request id on the same headers a repayment takes. Resending the same collection under that same request id answers
200 with the collection already standing. A second, different collection against a debt already collected answers 409 with LENDER-0325. Lender refuses a collection with 422 and LENDER-0326 when its collection instant is not RFC 3339, or when it has no request id. The same refusal covers a collector name longer than the field holds, or a request id already spent collecting a different debt.
The receivable names the contract it came from, so you find a contract’s receivables by narrowing the list to that loan account. It is not part of the contract’s own servicing view, because it is no longer the contract’s debt.
Lender carries the receivable at face value. The daily PDD sweep ages it along the ladder of the product it came from, and provisions the expected loss for its age. At the final stage, the sweep writes it off. A product whose chart can divert a returned payment must carry the three rules for that allowance and charge-off. Otherwise, Lender refuses the chart with 422 and LENDER-0406.
What happens downstream
Servicing emits
repayment.recorded, repayment_reversal.recorded, loan_schedule.prepayment_applied, loan_schedule.rescheduled, returned_payment_receivable.opened, returned_payment_receivable.collected, and returned_payment_receivable.written_off. A repayment, a reversal, and a prepayment record durable posting intents. Lender relays them to the ledger only when you configure the ledger relay. 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.