Disburse loan application

Validates disbursement eligibility, dispatches the resolving jurisdictional disbursement pipeline inside the parent transaction, and moves an approved application to disbursed. Idempotent: the lib-commons middleware enforces replay detection via X-Idempotency.

POST /api/v1/loan-applications/{id}/disburse

Disburse loan application

cURL

curl --request POST \
  --url https://lender.sandbox.lerian.net/api/v1/loan-applications/{id}/disburse \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "disbursedAt": "2026-06-14T12:00:00Z",
  "grossRequestedAmount": "50000.00",
  "loanAccountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "netDeliveredAmount": "49500.00",
  "currency": "BRL",
  "jurisdictionExtensions": {},
  "originationFeeAmount": "150.00",
  "trancheNumber": 2
}
'

200

{
  "assignedOfficerId": "officer-xyz",
  "borrowerId": "550e8400-e29b-41d4-a716-446655440002",
  "expectedDisbursementDate": "2026-06-14T12:00:00Z",
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "loanProductVersionId": "550e8400-e29b-41d4-a716-446655440000",
  "previewJurisdictionCode": "BR",
  "previewProfileVersion": "1.0.0",
  "previewScheduleSnapshotId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
  "requestedInstallments": 24,
  "requestedInterestRate": "0.00000100",
  "requestedPrincipalAmount": "50000.00",
  "status": "pending_approval",
  "approvalDecision": {
    "approvedAmount": "48000.00",
    "decidedBy": "<string>",
    "decisionAt": "2026-06-14T12:00:00Z",
    "id": "9f1c2d3e-4b5a-6789-abcd-ef0123456789",
    "note": "<string>"
  },
  "disbursementEvent": {
    "disbursedAt": "2026-06-14T12:00:00Z",
    "grossRequestedAmount": "50000.00",
    "id": "c3d4e5f6-a7b8-4901-acde-f01234567890",
    "loanAccountId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
    "netDeliveredAmount": "49500.00",
    "profileVersion": "1.0.0"
  },
  "rejectionDecision": {
    "decidedBy": "<string>",
    "decisionAt": "2026-06-14T12:00:00Z",
    "id": "b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
    "reason": "<string>"
  },
  "withdrawalDecision": {
    "decidedBy": "<string>",
    "decisionAt": "2026-06-14T12:00:00Z",
    "id": "b2c3d4e5-f6a7-4890-9bcd-ef0123456789",
    "reason": "<string>"
  }
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Idempotency · string · requerido

Canonical idempotency request ID (lib-commons enforcer reads this).

Parámetros de ruta

id · string<uuid> · requerido

Loan application identifier.

Ejemplo:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

Cuerpo

application/json

disbursedAt · string · requerido

Disbursement timestamp (RFC3339).

Ejemplo:

"2026-06-14T12:00:00Z"

grossRequestedAmount · string · requerido

Gross requested disbursement amount as a decimal string (e.g. "50000.00").

Ejemplo:

"50000.00"

loanAccountId · string · requerido

Loan account identifier (UUID).

Ejemplo:

"7c9e6679-7425-40de-944b-e07fc1f90ae7"

netDeliveredAmount · string · requerido

Net delivered disbursement amount as a decimal string (e.g. "49500.00").

Ejemplo:

"49500.00"

currency · string

Optional ISO-4217 currency assertion (3 uppercase letters). When present it MUST equal the loan application's currency (a double-entry guard); a divergence is rejected with 422. When omitted, the loan's own currency is used.

Required string length: 3

Pattern: ^[A-Z]{3}$

Ejemplo:

"BRL"

jurisdictionExtensions · object

Opaque per-jurisdiction disbursement payload, validated at the use-case layer.

originationFeeAmount · string

Optional per-disbursement origination fee as a decimal string (e.g. "150.00"). RETAINED from the borrower's cash at disbursement and credited to the product's deferred-income account, from which it is amortized back as yield over the contract's life (Res. CMN 4.966 art. 18). It is part of the disburse invariant: netDeliveredAmount MUST equal grossRequestedAmount minus the jurisdiction withholdings minus this fee. It is NOT a withholding (no third party is owed it) and it is never billed to the borrower on a schedule line. Omitted or empty defaults to "0".

Ejemplo:

"150.00"

trancheNumber · integer<int64>

Optional tranche position for a multi-tranche release: 1 for the first, 2 for the second, and so on. It must be exactly one more than the number of disbursements this application already carries. Omit it only for an application's SINGLE disbursement, which must then release the approved amount exactly — a second disbursement that declares no tranche is refused 409 LENDER-0201, and a wrong position or a total above the approved amount is refused 422 LENDER-0202.

Rango requerido: x >= 1

Ejemplo:

2

Respuesta

200

application/json

OK

assignedOfficerId · string · requerido

Authenticated officer who created the application (request subject), or empty on a system-originated application, which has no human officer. Whatever the identity provider issues as the subject: not necessarily a UUID.

Ejemplo:

"officer-xyz"

borrowerId · string<uuid> · requerido

Borrower identifier (UUID).

Ejemplo:

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

expectedDisbursementDate · string · requerido

Expected disbursement date (RFC3339, UTC).

Ejemplo:

"2026-06-14T12:00:00Z"

id · string · requerido

Loan application identifier (UUID).

Ejemplo:

"3fa85f64-5717-4562-b3fc-2c963f66afa6"

loanProductVersionId · string · requerido

Loan product version this application was created against (UUID).

Ejemplo:

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

previewJurisdictionCode · string · requerido

ISO-2 jurisdiction code resolved at preview time.

Ejemplo:

"BR"

previewProfileVersion · string · requerido

Jurisdiction profile version resolved at preview time.

Ejemplo:

"1.0.0"

previewScheduleSnapshotId · string · requerido

Preview schedule snapshot this application was created from (UUID).

Ejemplo:

"6ba7b810-9dad-11d1-80b4-00c04fd430c8"

requestedInstallments · integer<int64> · requerido

Number of installments requested.

Ejemplo:

24

requestedInterestRate · string · requerido

Requested monthly interest rate as a decimal string, scale 8 (e.g. "0.00000100").

Ejemplo:

"0.00000100"

requestedPrincipalAmount · string · requerido

Requested principal amount as a decimal string, minor-unit precision scale 2 (e.g. "50000.00").

Ejemplo:

"50000.00"

status · string · requerido

Lifecycle status: one of pending_approval, approved, rejected, withdrawn, disbursed.

Ejemplo:

"pending_approval"

approvalDecision · object

Approval facts; present only when the application is approved or disbursed.

Show child attributes

disbursementEvent · object

Disbursement facts; present only when the application is disbursed.

Show child attributes

rejectionDecision · object

Rejection facts; present only when the application is rejected.

Show child attributes

withdrawalDecision · object

Withdrawal facts; present only when the application is withdrawn.

Show child attributes