Skip to main content
POST
Refund an overpayment
When a repayment exceeds what the loan still owes, the excess stays on the loan as a credit balance and the loan moves to Overpaid. While it is in that state no further repayment can be posted to it — the loan is settled, and the customer is owed money back. This endpoint records that you have returned that money. It does not move money itself: the wallet credit is yours to make. Once recorded, the credit is cleared and the loan closes. Two equivalent forms — prefer the externalId form for partner integrations.
Credit the wallet first, then call this. There is no way to un-refund. If you record the refund with us and your wallet credit then fails, our ledger says the customer was repaid when they were not. The safe order is: move the money, then call this endpoint, retrying with the same idempotencyKey until it succeeds.

Path parameters

string
required
The loan’s externalId. On the /v1/loans/{loan_id}/refunds form, this is the numeric LMS id instead.

Request body

number
required
The overpayment you are refunding. It must equal the loan’s current overpayment exactly; a disagreement is rejected rather than corrected, because it means you are working from a figure that has since changed. You already hold this number, since you credited the wallet with it before calling, and stating it is what ties the two sides to the same figure.
string
required
Your own reference for the wallet credit that returned the money (max 100 characters). If a refund carrying this key has already been recorded on the loan, the original transaction is returned unchanged instead of a second refund being made. This is what makes a retry safe, and it keeps working after the loan has closed.
string
Optional value date in ISO yyyy-MM-dd, defaulting to today. Unlike a repayment there is no transactionAt: nothing about a refund depends on the exact instant.

Examples

Response

200 OK returns the refund transaction plus the loan’s position afterwards. The loan is now closed and carries nothing outstanding.
string
Closed (obligations met) after a successful refund. The overpayment is cleared and totalOverpaid on the loan returns to 0.
number
The credit that was returned.

Errors

Retrying a refund that already succeeded is not an error: with the same idempotencyKey you get the original transaction back with 200, for as long as the loan exists.

Avoiding overpayment in the first place

A refund is a recovery path, not a routine one. To stay out of it, read totalOutstanding immediately before each debit and debit exactly that figure — never a cached amount, never rounded up. See Record a repayment.