> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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. ## OpenAPI ````yaml /es/openapi/v3-current/lender.yaml post /api/v1/loan-applications/{id}/disburse openapi: 3.1.0 info: contact: email: contact@lerian.studio name: Lerian Studio url: https://lerian.studio description: >- Code-first OpenAPI 3.1 surface for the Lender service. Routes that move money are at-most-once per X-Idempotency: when one answers 5xx, the X-Idempotency-Fenced response header says whether that key is now refusing resends (true) or free to retry (false or absent). See docs/contracts/money-route-idempotency.md. license: name: Lerian Studio General License title: Lender API version: 1.0.0 servers: - url: https://lender.sandbox.lerian.net security: - BearerAuth: [] tags: - description: >- Caller session projection: validated subject and effective permissions for the presented token. name: Session - description: >- Ledger accounting operations: journal entries and accrual postings for loan accounts. name: Accounting - description: >- Loan application intake and lifecycle: submission, decisioning, and status. name: LoanApplications - description: >- Loan product catalog: definition, versioning, and activation of lending products. name: LoanProducts - description: >- Loan account servicing operations: balances, schedules, and account-level actions. name: Loan Accounts - description: >- Portfolio dashboard read operations: aggregated portfolio and performance views. name: Dashboard - description: >- Jurisdiction registry: supported jurisdiction profiles and their capabilities. name: Jurisdictions - description: >- Jurisdiction-specific loan application operations (Brazil origination surface). name: Loan Applications - description: >- Tax computation operations for jurisdiction-specific lending (e.g. Brazil IOF). name: Tax - description: >- Brazil consignado privado operations: contract lifecycle, exclusion repair, and compensating adjustments. name: Consignado - description: >- Credit-instrument document template registry: versioned drafting and publication of CCB clausulado. name: DocumentTemplates paths: /api/v1/loan-applications/{id}/disburse: post: tags: - LoanApplications summary: Disburse loan application description: >- 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. operationId: disburseLoanApplication parameters: - description: Loan application identifier. in: path name: id required: true schema: description: Loan application identifier. examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 format: uuid type: string - description: Canonical idempotency request ID (lib-commons enforcer reads this). in: header name: X-Idempotency required: true schema: description: >- Canonical idempotency request ID (lib-commons enforcer reads this). type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/DisburseLoanApplicationHumaRequest' required: true responses: '200': content: application/json: schema: $ref: '#/components/schemas/LoanApplicationHumaBody' description: OK '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unauthorized '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Forbidden '422': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Service Unavailable default: content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Error components: schemas: DisburseLoanApplicationHumaRequest: additionalProperties: false properties: currency: description: >- 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. examples: - BRL maxLength: 3 minLength: 3 pattern: ^[A-Z]{3}$ type: string disbursedAt: description: Disbursement timestamp (RFC3339). examples: - '2026-06-14T12:00:00Z' type: string grossRequestedAmount: description: >- Gross requested disbursement amount as a decimal string (e.g. "50000.00"). examples: - '50000.00' type: string jurisdictionExtensions: additionalProperties: true description: >- Opaque per-jurisdiction disbursement payload, validated at the use-case layer. type: object loanAccountId: description: Loan account identifier (UUID). examples: - 7c9e6679-7425-40de-944b-e07fc1f90ae7 type: string netDeliveredAmount: description: >- Net delivered disbursement amount as a decimal string (e.g. "49500.00"). examples: - '49500.00' type: string originationFeeAmount: description: >- 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". examples: - '150.00' type: string trancheNumber: description: >- 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. examples: - 2 format: int64 minimum: 1 type: integer required: - loanAccountId - grossRequestedAmount - netDeliveredAmount - disbursedAt type: object LoanApplicationHumaBody: additionalProperties: false properties: approvalDecision: $ref: '#/components/schemas/ApprovalDecisionHumaBody' description: >- Approval facts; present only when the application is approved or disbursed. assignedOfficerId: description: >- 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. examples: - officer-xyz type: string borrowerId: description: Borrower identifier (UUID). examples: - 550e8400-e29b-41d4-a716-446655440002 format: uuid type: string disbursementEvent: $ref: '#/components/schemas/DisbursementEventHumaBody' description: Disbursement facts; present only when the application is disbursed. expectedDisbursementDate: description: Expected disbursement date (RFC3339, UTC). examples: - '2026-06-14T12:00:00Z' type: string id: description: Loan application identifier (UUID). examples: - 3fa85f64-5717-4562-b3fc-2c963f66afa6 type: string loanProductVersionId: description: Loan product version this application was created against (UUID). examples: - 550e8400-e29b-41d4-a716-446655440000 type: string previewJurisdictionCode: description: ISO-2 jurisdiction code resolved at preview time. examples: - BR type: string previewProfileVersion: description: Jurisdiction profile version resolved at preview time. examples: - 1.0.0 type: string previewScheduleSnapshotId: description: Preview schedule snapshot this application was created from (UUID). examples: - 6ba7b810-9dad-11d1-80b4-00c04fd430c8 type: string rejectionDecision: $ref: '#/components/schemas/ReasonedDecisionHumaBody' description: Rejection facts; present only when the application is rejected. requestedInstallments: description: Number of installments requested. examples: - 24 format: int64 type: integer requestedInterestRate: description: >- Requested monthly interest rate as a decimal string, scale 8 (e.g. "0.00000100"). examples: - '0.00000100' type: string requestedPrincipalAmount: description: >- Requested principal amount as a decimal string, minor-unit precision scale 2 (e.g. "50000.00"). examples: - '50000.00' type: string status: description: >- Lifecycle status: one of pending_approval, approved, rejected, withdrawn, disbursed. examples: - pending_approval type: string withdrawalDecision: $ref: '#/components/schemas/ReasonedDecisionHumaBody' description: Withdrawal facts; present only when the application is withdrawn. required: - id - loanProductVersionId - borrowerId - assignedOfficerId - status - requestedPrincipalAmount - requestedInterestRate - requestedInstallments - expectedDisbursementDate - previewProfileVersion - previewJurisdictionCode - previewScheduleSnapshotId type: object Detail: additionalProperties: false properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object ApprovalDecisionHumaBody: additionalProperties: false properties: approvedAmount: description: >- Approved amount as a decimal string, minor-unit precision scale 2 (e.g. "48000.00"). examples: - '48000.00' type: string decidedBy: description: Authenticated subject who approved the application. type: string decisionAt: description: Approval decision timestamp (RFC3339, UTC). examples: - '2026-06-14T12:00:00Z' type: string id: description: Approval decision identifier (UUID). examples: - 9f1c2d3e-4b5a-6789-abcd-ef0123456789 type: string note: description: Optional approval note supplied by the deciding officer. type: string required: - id - approvedAmount - decisionAt - decidedBy type: object DisbursementEventHumaBody: additionalProperties: false properties: disbursedAt: description: Disbursement timestamp (RFC3339, UTC). examples: - '2026-06-14T12:00:00Z' type: string grossRequestedAmount: description: >- Gross requested disbursement amount as a decimal string, minor-unit precision scale 2 (e.g. "50000.00"). examples: - '50000.00' type: string id: description: Disbursement event identifier (UUID). examples: - c3d4e5f6-a7b8-4901-acde-f01234567890 type: string loanAccountId: description: Loan account credited by this disbursement (UUID). examples: - 7c9e6679-7425-40de-944b-e07fc1f90ae7 type: string netDeliveredAmount: description: >- Net delivered disbursement amount as a decimal string, minor-unit precision scale 2 (e.g. "49500.00"). examples: - '49500.00' type: string profileVersion: description: Jurisdiction profile version applied by the disbursement pipeline. examples: - 1.0.0 type: string required: - id - loanAccountId - grossRequestedAmount - netDeliveredAmount - disbursedAt - profileVersion type: object ReasonedDecisionHumaBody: additionalProperties: false properties: decidedBy: description: Authenticated subject who recorded the decision. type: string decisionAt: description: Decision timestamp (RFC3339, UTC). examples: - '2026-06-14T12:00:00Z' type: string id: description: Decision identifier (UUID) for the rejection or withdrawal. examples: - b2c3d4e5-f6a7-4890-9bcd-ef0123456789 type: string reason: description: Free-text reason for the rejection or withdrawal. type: string required: - id - decisionAt - decidedBy - reason type: object ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ````