Skip to main content

Disbursement

Disbursement is paying the loan out at activation. Who moves the money — and when its status resolves — depends on how the loan was originated. Every payout is recorded as a Disbursement with a source and a status, visible on the loan's Disbursements tab.

Two sources​

Loanly-disbursed (console / internal origination) — Loanly pays the borrower through the bank rail. The payout is asynchronous: it never blocks the request.

Externally funded (partner origination) — the originating partner funds the loan from its own system, then confirms it via /api/v1/loans/{id}/activate. Loanly records the payout as an external disbursement (with the partner's reference) for audit, but never touches a bank rail. The disbursement is Completed on arrival.

The async model (Loanly-disbursed)​

Activation does not call the bank. Instead it:

  1. records a Disbursement as Pending — capturing the destination account and amount (this row is the durable "sending" record),
  2. opens the ledger with the outstanding principal, and
  3. flips the loan to Active immediately.

A background sweep (dispatch-disbursements, every few minutes on the admin worker) then dispatches each pending payout to the rail and records the outcome:

Pending ──dispatch──▶ Completed        (paid; external reference + timestamp recorded)
        └─dispatch──▶ Failed  ──retry──▶ …   (flagged for ops; retried by a later sweep)

Retries are safe: the rail's per-loan booking id is idempotent, so a re-attempt never pays a borrower twice. A failed payout leaves the loan Active with the failure recorded on the disbursement — it's surfaced for operators, not rolled back.

:::note Why "Active before the money lands"? Servicing (due dates, aging) is driven by the schedule, not by payout timing, and separating activation from the rail keeps a slow or flaky bank from blocking the request. The trade-off — a loan can be Active with a still-settling payout — is deliberate; the disbursement status is the source of truth for whether the borrower has actually been paid. :::

What we store​

The Disbursement row is the whole record: amount, destination bank account, source (Loanly / External), status (Pending / Completed / Failed), the rail's external reference, any failure reason, and the disbursed timestamp. Loanly holds no separate payout profile — the account is captured on the disbursement at activation (Loanly-disbursed), or omitted entirely when the partner funded it.