> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lead.bank/llms.txt
> Use this file to discover all available pages before exploring further.

# The Funding Object

> Field-level reference for the Funding object — your instruction to Lead to originate loan principal: the principal decomposition, fee fields, the three-state lifecycle, and sandbox testing.

A Funding is your instruction to Lead to **originate principal** — Lead moves the funds from a Lead GL to your program's funding FBO account, and the drawn amount becomes a [receivable on Lead's books](/products/lending/receivables-and-the-daily-sale). This is an **executing** object ([Executing vs. Reporting](/core-concepts/platform/executing-vs-reporting)): the call moves money. A non-revolving Balance typically has one Funding; a revolving Balance takes a Funding per draw.

## Creating a Funding

`POST /v0/fundings` with a required `Idempotency-Key` header (5–255 characters). Prerequisites, enforced at creation:

* The referenced [Balance](/products/lending/balance-object) must be **`active`**, and if it has an `expected_maturity_date`, that date must not be in the past.
* `currency_code` must match the Balance's currency.
* For `non_revolving` Balances: the sum of all `principal.*` fields on this request **plus** the `principal.*` sums of every prior Funding in `posted` *or `processing`* status against the same Balance must not exceed the Balance's `max_funding_amount` — in-flight draws count against the ceiling.

| **Field**              | **Type** | **Required** | **Description**                                   |
| :--------------------- | :------- | :----------- | :------------------------------------------------ |
| `subledger_balance_id` | string   | Yes          | The Balance being drawn against.                  |
| `currency_code`        | enum     | Yes          | `USD` only today; must match the Balance.         |
| `principal`            | object   | Yes          | The funded principal, decomposed — see below.     |
| `other_fees`           | object   | No           | Fees Lead needs for bookkeeping only — see below. |
| `metadata`             | object   | No           | Arbitrary key-value pairs (e.g., your draw ID).   |

### `principal` (object)

The total of these fields is the loan principal. **Upon funding, this amount is considered disbursed, and Lead begins applying imputed interest** ([Sales Settlement Amount](/products/funding-and-receivables/sales-settlement-amount)).

| **Field**                         | **Type** | **Description**                                                                                                                                                                  |
| :-------------------------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `external_disbursement_amount`    | integer  | The portion made available for external disbursement at funding time (minor units).                                                                                              |
| `withheld_amount`                 | integer  | The portion withheld and not disbursed externally at funding time (minor units). **Invariant: at least one of `external_disbursement_amount` or `withheld_amount` must be > 0.** |
| `merchant_origination_fee_amount` | integer  | Origination fees charged to the merchant, **included in** the principal (minor units). Must be **less than** `external_disbursement_amount + withheld_amount`.                   |

### `other_fees` (object)

| **Field**                         | **Type** | **Description**                                                                                                                                                                                                                                                                                                                                                              |
| :-------------------------------- | :------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `borrower_origination_fee_amount` | integer  | **Non-capitalized** origination fee charged to the borrower at funding (minor units) — not part of principal; Lead needs it for bookkeeping only. When you later report the disbursement transaction, its `fee_amount` must equal this value or the file fails `funding_fee_amount_mismatch` ([troubleshooting](/file-reference/balances-and-transactions/troubleshooting)). |

### Worked example: a \$1,000 BNPL purchase

A customer finances a 100 origination fee, half the purchase disburses to the merchant now and half is withheld pending delivery, and the borrower pays a separate \$2 processing fee:

```json theme={null}
{
  "subledger_balance_id": "subledger_balance_1HCpXwx2EK9oYluWbacgeCnFcLf",
  "currency_code": "USD",
  "principal": {
    "external_disbursement_amount": 45000,
    "withheld_amount": 45000,
    "merchant_origination_fee_amount": 10000
  },
  "other_fees": { "borrower_origination_fee_amount": 200 },
  "metadata": { "client_draw_id": "X67BU" }
}
```

Principal = $450 \+ $450 + $100 \= $1,000 — the merchant fee is *inside* principal (the borrower owes it); the borrower's \$2 fee rides outside as `other_fees`.

## **Lifecycle**

| Status       | Meaning                                                                                |
| ------------ | -------------------------------------------------------------------------------------- |
| `processing` | Created; Lead is moving the funds. Counts against `max_funding_amount`.                |
| `posted`     | Funds have moved to your funding FBO; the receivable exists on Lead's books. Terminal. |
| `rejected`   | The Funding will not complete — see the `rejection` object. Terminal.                  |

The `rejection` object is always present on the Funding (empty strings when not rejected), with `reason` (currently the single enum `internal_error` — the spec notes Lead may add values as non-breaking changes, so handle unknown reasons gracefully) and `details` (reserved for future use). Status changes are delivered by webhook (`funding.posted` **\[VERIFY event name against the webhooks reference]**); a Balance cannot be reported into a terminal status while a Funding against it is still `processing`.

## **Sandbox**

In sandbox, Fundings stay `processing` until you advance them: call [Simulate Advance Funding](/api-reference/endpoint/funding/advance-a-funding) to transition to `posted` and exercise your downstream flows end to end ([Originate Your First Loan](/get-started/quickstart/originate-your-first-loan)).

## **Example Funding Object**

```json theme={null}


{
  "id": "funding_0o5Fs0EELR0fUjHjbCnEtdUwQe3",
  "subledger_balance_id": "subledger_balance_1HCpXwx2EK9oYluWbacgeCnFcLf",
  "currency_code": "USD",
  "principal": {
    "external_disbursement_amount": 100000,
    "withheld_amount": 1000,
    "merchant_origination_fee_amount": 100
  },
  "other_fees": { "borrower_origination_fee_amount": 200 },
  "metadata": { "client_draw_id": "X67BU" },
  "status": "processing",
  "rejection": { "reason": "", "details": "" },
  "created_at": "2025-09-02T11:01:36Z",
  "updated_at": "2025-09-02T11:05:00Z"
}
```

Full schemas: [Create a Funding](/api-reference/endpoint/funding/create-a-funding) · [Retrieve a Funding](/api-reference/endpoint/funding/retrieve-a-funding).