Record repayment

Records a repayment allocation for an active loan account. Idempotency is enforced in the use case on the required X-Idempotency key: a reused key with different facts yields 409. A malformed UUID or amount yields 422. Deduplication is by X-Idempotency key ALONE: the same amount, on the same account, on the same effective date, resent under a NEW key books a SECOND payment and answers 201. A borrower may legitimately pay the same amount twice, and no field in the request separates that from an accidental resend, so this route carries no business-fact fence — unlike disbursement, which does. Retry under the ORIGINAL key, which replays the original answer and moves nothing; a double that did book is undone on POST /api/v1/loan-accounts//transactions//reverse, newest effective instant first (payments sharing one effective instant reverse in any order). Both figures are enqueued for the ledger in the same transaction, and the ledger posts them through the relay: appliedAmount against the receivable, overpaymentAmount to the product’s unapplied cash account (its collection_unapplied rule), so the two always add up to the cash received. A reversal gives back both. Money dated before a payment no reversal undid (a reversed due-day settlement still counts), a prepayment or a reschedule the contract holds, on an earlier São Paulo day or at an earlier instant, is refused with 409 (LENDER-0302) and writes nothing. Money dated on a São Paulo civil day after today is refused with 422 (LENDER-0395) and writes nothing; a later hour of today is accepted. Money dated on a São Paulo civil day before the contract’s disbursement is refused with 422 (LENDER-0985) and writes nothing; an earlier hour of that day is accepted.

POST /api/v1/loan-accounts/{id}/repayments

Record repayment

cURL

curl --request POST \
  --url https://lender.sandbox.lerian.net/api/v1/loan-accounts/{id}/repayments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "125.00",
  "effectiveDate": "2026-06-14T17:30:00Z",
  "transactionDate": "2026-06-14T17:30:00Z"
}
'

201

{
  "allocations": [
    {
      "dueDate": "2026-06-14",
      "feesAmount": "3.50",
      "fullyPaid": true,
      "installmentNumber": 3,
      "interestAmount": "20.00",
      "penaltiesAmount": "1.50",
      "principalAmount": "100.00",
      "totalAmount": "125.00"
    }
  ],
  "appliedAmount": "125.00",
  "backdated": true,
  "effectiveDate": "2026-06-14",
  "loanAccountId": "550e8400-e29b-41d4-a716-446655440000",
  "overpaymentAmount": "0.00",
  "transactionId": "550e8400-e29b-41d4-a716-446655440001",
  "prepaidInstallment": {
    "discount": "14.96",
    "dueDate": "2026-06-15",
    "installmentNumber": 1,
    "presentValue": "507.27"
  },
  "requestId": "550e8400-e29b-41d4-a716-446655440010"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string

Idempotency key of the payment: 1 to 128 characters of letters, digits and - _ . :. The route refuses a request without it, or with a blank or unusable one (LENDER-0301). X-Request-ID is never read as the key.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440011"

Parámetros de ruta

id · string<uuid> · requerido

Loan account identifier (UUID).

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

Cuerpo

application/json

amount · string · requerido

Repayment amount in major currency units (e.g. "125.00"). Must be positive with at most 2 fractional digits.

Ejemplo:

"125.00"

effectiveDate · string

The moment the money moved, as a full RFC 3339 instant with a time and an offset. A bare YYYY-MM-DD calendar date is refused with LENDER-0348. Omit it and transactionDate, and Lender stamps the tenant's business now.

Ejemplo:

"2026-06-14T17:30:00Z"

transactionDate · string

The moment the money moved, as a full RFC 3339 instant, read when effectiveDate is absent. A bare YYYY-MM-DD calendar date is refused with LENDER-0348.

Ejemplo:

"2026-06-14T17:30:00Z"

Respuesta

201

application/json

Created

allocations · object[] | null · requerido

Per-installment allocation breakdown.

Show child attributes

appliedAmount · string · requerido

Amount applied to the loan (2 d.p. string).

Ejemplo:

"125.00"

backdated · boolean · requerido

True if the repayment effective date is before the business date.

effectiveDate · string · requerido

YYYY-MM-DD São Paulo day of the instant the money moved: the one the request named, or the tenant's business now Lender stamped when it named none. A replay answers the day of the original payment.

Ejemplo:

"2026-06-14"

loanAccountId · string · requerido

Loan account UUID.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

overpaymentAmount · string · requerido

Part of the payment that no instalment due on or before the effective date absorbed (2 d.p. string). It is not an excess over the whole balance: instalments due later take none of the payment, so paying ahead of the schedule lands here.

Ejemplo:

"0.00"

transactionId · string · requerido

Recorded repayment transaction UUID.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440001"

prepaidInstallment · object

The instalment this payment covers ahead of the schedule: on a product version that prepays automatically, an overpaymentAmount of at least the day's present value of the next instalment promises it, and it closes at that present value on its due date from the held overpayment. Omitted when the payment promises nothing.

Show child attributes

requestId · string

X-Idempotency key echoed from the request.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440010"