Funding & disbursement

Funding is modeled as an intent because approval, rail submission, settlement, and ledger posting happen at different times. The intent explains where money is; the ledger explains what the customer owes. Fundings are loan-scoped: every payout lives under /v1/loans/{loanId}/fundings.

Funding lifecycle

LifecycleFunding

CREATEDrecipient and amount captured

›

VALIDATEDcontract and destination pass

›

APPROVAL_REQUIREDmaker complete

›

APPROVEDchecker authorizes

›

SUBMITTEDsystem releases payout to the rail

›

PROCESSINGrail in flight

›

SETTLED_PENDING_POSTfunds released

›

POSTEDledger and lifecycle updated

APPROVAL_REQUIRED→REJECTEDchecker declines with reason code

APPROVED→CANCELLEDcancelled any time before submission

SETTLED_PENDING_POST→POSTED_FAILED_REVIEWnever resubmit payout

Fund Harbor

A DISBURSEMENT requires the loan to be APPROVED—not yet active—and its amount may not exceed the approved principal. A DISBURSEMENT_HOLD restriction blocks creation.

curl -X POST "$BASE/v1/loans/7204/fundings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "LendEasy-Tenant: demo-lender" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: harbor-initial-funding-01" \
  -d '{
    "amount": "8400.00",
    "currency": "USD",
    "fundingType": "DISBURSEMENT",
    "recipientType": "BORROWER",
    "recipientRef": "412",
    "instrumentId": 705,
    "rail": "ACH",
    "reason": "Initial disbursement for approved loan."
  }'

{ "fundingId": 5107, "loanRef": "7204", "status": "APPROVAL_REQUIRED" }

Harbor’s $252 prepaid origination fee is a loan charge assessed at disbursement, not a second payout; the posted advance establishes the $8,400 receivable while Maya’s proceeds are $8,148. See Accounting for the balanced entries.

Approval: maker and checker are different people

Every funding starts in APPROVAL_REQUIRED. There is no submit route—once approved, the system releases the payout to the rail itself.

• POST /v1/loans/7204/fundings/5107/approve takes no body. The creator can never approve their own funding.
• POST …/reject records a required reasonCode.
• POST …/cancel (reasonCode, optional comment) works only before money movement—while CREATED, VALIDATED, APPROVAL_REQUIRED, or APPROVED. Cancelling an already-cancelled funding is a no-op.

Approval and rejection return the command envelope, for example { "resourceId": 5107 }; read the funding for its canonical state with GET /v1/loans/7204/fundings/5107.

Recipients and ownership

A funding recipient is BORROWER or EXTERNAL_PARTY—a merchant, dealer, healthcare provider, school, vendor, or investor. Before submission LendEasy confirms:

• the recipient reference resolves to the borrower or an active, verified external party;
• the payment instrument belongs to that recipient and is ACTIVE with verificationState: "VERIFIED";
• the requested rail is within the instrument’s capabilities;
• a disbursement does not exceed the approved principal; and
• no restriction blocks money movement.

Juniper’s financed purchase can pay its merchant as an external-party funding while the down payment settles separately. The loan activates only when the financed payout posts.

Value-dated posting

The disbursement posts value-dated on release: the accrual start and activation date come from the date funds left the lender’s control, not from createdAt, the approval time, or the moment the rail accepted the request. Those timestamps all remain on the funding record so the sequence stays auditable, but only the posted value date drives loan calculations.

Record an external payout

When treasury moves the money—for example a wire—record it instead of creating a rail payout:

POST /v1/loans/7204/fundings/record-external

The body carries amount, currency, fundingType, recipientType, recipientRef, a unique externalRecordRef, and a reason. No instrument or rail is involved and no money moves; the funding enters reconciliation as RECORDED_EXTERNAL.

Refund fundings

fundingType: "REFUND" moves money out for a ledger effect that already exists—a governed refund command such as credit-balance refund or payout refund creates the balance effect, and the funding pays it. The funding itself does not post a second ledger transaction, so the books can never show a refund twice. A refund funding follows the same approval, submission, and posting path as a disbursement.

Posting failure and repair

Once funds are released, a missing ledger post routes the funding to POSTED_FAILED_REVIEW. Operators repair or confirm the single posting; the payout is never resubmitted, and a recovery—if money went to the wrong destination—is a separate governed workflow. Differences between provider events, fundings, and the ledger surface as reconciliation exceptions, which never auto-close a mismatch solely because totals happen to net to zero.