Reverse loan account transaction

Creates an immutable compensating transaction and preserves reversal lineage. The reversal’s effective date is DERIVED from the payment being reversed and is not accepted in the request; a body carrying effectiveDate is refused 422. Idempotency is enforced in the use case on the required X-Idempotency key: a reused key with different facts yields 409. A malformed loan account UUID yields 422; an unknown transaction yields 404; a payment already reversed yields 409. A partial prepayment reverses too: a new transaction brings back the schedule it retired and frees the payments recorded before it. A payoff does not, nor does a partial paid through a collected quote (404). A partial of a month a close decided is REFUSED 422 with LENDER-0356 when the tenant’s business date runs ahead of the wall clock. A reversal is REFUSED 422 when the loan account carries a payment whose effective timestamp is strictly later than the reversed payment’s, or equal to it and recorded after it, or a schedule version dated strictly later than it or recorded at or after it was recorded. A payment whose whole amount stayed held cash, dated on a day after the payoff that settled the contract, is reversed: the contract stays settled and only that held cash goes back. When the payment left held cash the client already refunded the borrower, a settled contract whose ending payment is reversed reopens and the refunded part opens as a returned-payment receivable of the borrower in the same transaction, answered in returnedPaymentReceivableId; a product whose chart of accounts declares no returned-payment rules REFUSES it 422 with LENDER-0988, naming how much was refunded: the operator recovers that money outside the Lender. The problem document names which fact blocks, in errors[0].message: REVERSAL_REFUSED_LATER_PAYMENT (the borrower paid again — use the compensating-adjustment path), REVERSAL_REFUSED_LATER_SCHEDULE_VERSION (the schedule was re-agreed — the remedy is a new schedule version, or, when the later version is a partial prepayment, to reverse it first), or REVERSAL_REFUSED_LATER_FACTS_EXIST (both). A partial prepayment is REFUSED 422 with LENDER-0629 when the contract changed before it (a tranche, or a reschedule or renegotiation of a contract with fees): the reversal would not restore the books. An automatic prepayment discount is REFUSED 422 on its own: reversing its due day’s settlement reverses it too.

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

Reverse loan account transaction

cURL

curl --request POST \
  --url https://lender.sandbox.lerian.net/api/v1/loan-accounts/{id}/transactions/{transactionId}/reverse \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "<string>",
  "jurisdictionCode": "BR",
  "profileVersion": "1.0.0"
}
'

200

{
  "amount": "125.00",
  "destination": "revived",
  "effectiveDate": "2026-06-14",
  "loanAccountId": "550e8400-e29b-41d4-a716-446655440000",
  "originalTransactionId": "550e8400-e29b-41d4-a716-446655440001",
  "profileVersion": "1.0.0",
  "reason": "<string>",
  "transactionId": "550e8400-e29b-41d4-a716-446655440002",
  "jurisdictionCode": "BR",
  "requestId": "550e8400-e29b-41d4-a716-446655440010",
  "returnedPaymentReceivableId": "550e8400-e29b-41d4-a716-446655440003"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string

Idempotency key of the reversal: 1 to 128 characters of letters, digits and - _ . :. The route refuses a request without it, or with a blank or unusable one (LENDER-0317). 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"

transactionId · string · requerido

Identifier of the payment or partial prepayment to reverse: up to 128 characters, 141 for the arrears payments a prepayment settled first (id + -arrears, id + -arrears-held).

Required string length: 1 - 141

Ejemplo:

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

Cuerpo

application/json

reason · string · requerido

Operator-supplied reversal reason.

Minimum string length: 1

jurisdictionCode · string

Optional jurisdiction code.

Ejemplo:

"BR"

profileVersion · string

Product profile version applied to the reversal.

Ejemplo:

"1.0.0"

Respuesta

200

application/json

OK

amount · string · requerido

Reversed amount (2 d.p. string).

Ejemplo:

"125.00"

destination · enum<string> · requerido

Where the reversed money went: always 'revived', the debt returned to this contract and its schedule is back.

Opciones disponibles: revived

Ejemplo:

"revived"

effectiveDate · string · requerido

YYYY-MM-DD São Paulo day of the payment the reversal undoes.

Ejemplo:

"2026-06-14"

loanAccountId · string · requerido

Loan account UUID.

Ejemplo:

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

originalTransactionId · string · requerido

Reversed original transaction UUID.

Ejemplo:

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

profileVersion · string · requerido

Product profile version applied to the reversal.

Ejemplo:

"1.0.0"

reason · string · requerido

Operator-supplied reversal reason.

transactionId · string · requerido

Compensating reversal transaction UUID.

Ejemplo:

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

jurisdictionCode · string

Jurisdiction code applied to the reversal.

Ejemplo:

"BR"

requestId · string

X-Idempotency key echoed from the request.

Ejemplo:

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

returnedPaymentReceivableId · string<uuid>

Identifier of the returned-payment receivable this reversal opened for the held cash the client had already refunded the borrower. Absent when no held cash was refunded.

Ejemplo:

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