Prepay loan account

Appends an immutable prepayment schedule version and recalculation trigger. BR accounts require quoteId; amount-only prepayment is available only for non-BR accounts. When both are provided, amount must equal the quote’s net settlement amount, or the request yields 422 (LENDER-0351). Idempotency is enforced through the X-Idempotency header; a reused key with different facts yields 422 (IDEMPOTENCY_KEY_REUSE). A missing required BR quote, malformed UUID, or invalid amount yields 422. Deduplication is by key ALONE: an amount-only settlement resent under a NEW key books a SECOND settlement, so retry under the ORIGINAL key. A BR quote is one-shot and bounds this by itself — a new key carrying an already-accepted quoteId is refused with 409 (LENDER-0355) and writes nothing, while a new key carrying a new quote is a newly priced settlement and is meant to book. A retry of the same request after the contract closed answers 201 with the version it wrote. A partial whose money is 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. A quote accepted with money dated on a São Paulo civil day before the contract’s disbursement is refused with 422 (LENDER-0985) and writes nothing. A partial quote settled while a full-settlement quote on the contract is still payable is refused with 409 (LENDER-0375) and writes nothing; liveQuoteId and liveQuoteExpiresAt name that quote.

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

Prepay loan account

cURL

curl --request POST \
  --url https://lender.sandbox.lerian.net/api/v1/loan-accounts/{id}/prepayments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "businessDate": "2026-06-14",
  "transactionId": "<string>",
  "amount": "100.00",
  "effectiveDate": "2026-06-14T17:30:00Z",
  "quoteId": "550e8400-e29b-41d4-a716-446655440020"
}
'

201

{
  "previousScheduleVersionId": "550e8400-e29b-41d4-a716-446655440031",
  "scheduleVersion": {
    "createdAt": "2026-06-14T12:00:00Z",
    "id": "550e8400-e29b-41d4-a716-446655440030",
    "installments": [
      {
        "dueDate": "2026-06-14T12:00:00Z",
        "feesAmount": "3.50",
        "interestAmount": "20.00",
        "number": 3,
        "penaltiesAmount": "1.50",
        "principalAmount": "100.00",
        "principalRemaining": "100.00",
        "totalAmount": "125.00"
      }
    ],
    "loanAccountId": "550e8400-e29b-41d4-a716-446655440000",
    "reason": "<string>",
    "triggerTransactionId": "<string>",
    "versionNumber": 2,
    "financedTaxAmount": "25.72",
    "predecessorVersionId": "550e8400-e29b-41d4-a716-446655440031",
    "pricedAtMonthlyRate": "0.025",
    "restructuring": {
      "defaultIsRestructuring": true,
      "isRestructuring": true,
      "recordedAt": "2026-06-14T12:00:00Z",
      "recordedBy": "officer-xyz",
      "justification": "<string>"
    },
    "waivedLateCharges": "7.30"
  },
  "substantialRenegotiation": {
    "replacedLifecycleState": "renegotiated",
    "replacementLoanAccountId": "550e8400-e29b-41d4-a716-446655440040",
    "replacementLoanApplicationId": "550e8400-e29b-41d4-a716-446655440041",
    "trigger": "present_value"
  }
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

Canonical idempotency request ID.

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

businessDate · string · requerido

YYYY-MM-DD business date applied to the prepayment.

Ejemplo:

"2026-06-14"

transactionId · string · requerido

Operator-supplied prepayment transaction identifier.

Maximum string length: 128

amount · string

Prepayment amount (2 d.p. string). Amount-only prepayment is available only for non-BR accounts; BR accounts require quoteId.

Ejemplo:

"100.00"

effectiveDate · string

The moment the settlement 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 Lender stamps the tenant's business now.

Ejemplo:

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

quoteId · string

Settlement quote identifier. Required when amount is empty.

Ejemplo:

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

Respuesta

201

application/json

Created

previousScheduleVersionId · string · requerido

Predecessor schedule version UUID.

Ejemplo:

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

scheduleVersion · object · requerido

The newly appended immutable schedule version.

Show child attributes

substantialRenegotiation · object

Present only when a reschedule was a SUBSTANTIAL renegotiation under Res. CMN 4.966/2021 art. 22: this contract was ended (scheduleVersion is its last ladder, at zero) and a replacement contract now carries the debt. Never present on a restructuring, which stays on its contract. Omitted on every other outcome.

Show child attributes