> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/split-funding.md).

# Split Funding

The Split Funding Program lets a partner decide, per payment, exactly how much a merchant keeps. The consumer pays the full ticket, the merchant is settled the agreed amount with no transaction fee deducted, and Bead withholds the difference and later pays it to the partner.

Use this page when a merchant is enrolled in the Split Funding Program. For standard payment creation, see [Create Payment](/payments/create-payment.md).

> **Read the next two sections before you scope the work.** This program is normally operated with a consumer fee, and it places real obligations on you rather than on Bead. Confirm you can meet all four requirements in [What this program requires of you](#what-this-program-requires-of-you) before you commit to an integration.

### Where the money for Bead's fee comes from

Start here, because it determines whether the program is usable for your merchant at all.

The merchant is settled `merchantPortion` exactly, with no transaction fee deducted. Every cost Bead charges is therefore recovered from the partner portion. That means the partner portion has to be large enough to cover Bead's per-payment fee on every tender you offer, plus a share of the settlement fee.

There are only two places that money can come from.

| Approach                          | What happens                                                                                                                        | Consequence                                                                                                 |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **A consumer fee you add on top** | `total` is the merchant's price plus your fee. `merchantPortion` is the price the merchant billed. The partner portion is your fee. | The merchant is settled the exact amount they billed. This is the intended use of the program.              |
| **The merchant's own margin**     | `total` is the merchant's price. You set `merchantPortion` below that price and the merchant absorbs the difference.                | Workable, but the merchant is no longer receiving exact settlement, which is the reason the program exists. |

There is no third option. If the partner portion does not cover Bead's fee on a tender, that tender is removed from the payment page. If it covers none of the offered tenders, the payment is rejected outright. See [Coverage is checked when the payment is created](#coverage-is-checked-when-the-payment-is-created).

In practice this makes the Split Funding Program a consumer fee program. You can run it without one, but only by reducing what the merchant keeps.

### What this program requires of you

Because the fee is collected from the consumer, in your environment, under your disclosure, the obligations sit with you. Bead receives computed dollar amounts and processes them.

**Four requirements. If your solution cannot meet all four, this program is not a fit.**

**1. You understand consumer fee law and can apply it.** State-level surcharge and convenience fee rules differ, some states prohibit the practice outright, and several impose pricing-transparency rules that reach beyond card tenders. Platform terms add a second layer that varies by tender. You are the party making the determination of what a consumer may be charged, for which tender, in which state. See [Consumer Fee Passthrough for Wallet and Crypto Tenders](/faqs-and-troubleshooting/payments-faqs/consumer-fee-passthrough-for-wallet-and-crypto-tenders.md).

**2. Your solution supports a tender-based consumer fee.** This is a hard technical requirement, not a recommendation. Bead's buy rates differ substantially between tenders, so one flat fee applied to every tender will be overpriced on the cheap ones and underwater on the expensive ones. An underwater fee does not error: the coverage check removes those tenders from the consumer's payment page, and names them back to you on the creation response. Your fee logic must be able to vary by tender, which in turn means determining the tender in your own environment before you create the payment, or sizing for the most expensive tender you offer. Permissibility also varies by tender, so a single fee can be legally wrong as well as commercially wrong.

**3. You perform the fee calculation.** Bead does not calculate a consumer fee. There is no rate field, no percentage field and no fee schedule input anywhere on the payment request. You compute the figures and send three dollar amounts that balance to the cent. Bead can process a fee you have already calculated. It cannot derive one.

**4. You handle consumer notification and presentment.** Bead's hosted payment page does not disclose, itemize or display a consumer fee. It shows a single total. Disclosure to the consumer happens in your checkout, before the payment is created, in whatever form the applicable rules require.

> **This is why the program suits solution providers and resellers who already operate consumer fee collection.** It is not a capability a merchant can switch on, and it is not something an integrator can adopt without building the fee logic, the per-tender sizing and the disclosure around it. If you are evaluating this program, plan for that work.

> **You send dollar amounts, not percentages.** There is no rate, percentage or fee schedule anywhere on this request. You calculate the figures in your own environment and send three computed dollar amounts that must balance to the cent. Any percentage in this page describes arithmetic you perform before you call Bead.

### How it differs from standard processing

On standard processing, Bead calculates the transaction fee from the merchant's fee configuration and deducts it from the merchant's settlement.

On the Split Funding Program:

* Your integration sends the exact amount the merchant should keep.
* Bead settles that amount, with no transaction fee applied. The merchant's fee configuration is not consulted at all.
* The remainder is withheld at settlement and paid to the partner on a schedule, net of Bead's fee.
* The merchant is never billed afterwards and never sees a later deduction.

Enrolled merchants can still send ordinary payments. Omit the split funding block and the payment is processed normally. Mixed traffic on one merchant is supported and the two kinds settle side by side, with one consequence for settlement fees described in [Settlement behavior](#settlement-behavior). Those ordinary payments compensate you through your standard processing arrangement rather than through the distribution, so a merchant running both kinds is compensated through both routes, with every transaction counted once.

### Two destinations, fixed by role

This is the most important boundary on the program, and the one most often misread, because the term "split funding" carries assumptions from card processing that do not apply here.

**A payment can fund exactly two accounts, and which two is not yours to choose:**

| Destination                    | What it receives                                            |
| ------------------------------ | ----------------------------------------------------------- |
| The merchant's account on file | The merchant portion, in full, with nothing deducted        |
| Your partner account on file   | The withheld partner portion, with every Bead cost deducted |

"On file" means the bank account already held on that entity's record at Bead. For the merchant that is the account established at boarding. For you it is the account on your designated representing merchant record. Neither can be overridden on a payment.

**You direct the amounts. You do not direct the destinations.** Specifically, none of the following is possible today:

* Naming a payee, account or routing detail on the payment.
* Splitting a payment three or more ways.
* Funding a third party who is neither the merchant nor you.
* Registering a sub-merchant to receive part of a payment.
* Sending a merchant's proceeds to a second account belonging to that merchant, for example settling the sale to a retail account and a fee to an operating account.
* Sending your portion anywhere other than your own account on file.

If an integration needs any of those, this program is not the mechanism. Raise it with your Bead integration contact rather than trying to model it with the amounts.

### The three amounts

Every split funding payment carries three amounts.

| Amount            | Description                                                               |
| ----------------- | ------------------------------------------------------------------------- |
| `total`           | What the consumer pays. Must exactly equal `requestedAmount`.             |
| `merchantPortion` | The exact amount settled to the merchant. No transaction fee is deducted. |
| `partnerPortion`  | The amount withheld at settlement for later distribution to the partner.  |

All three are computed dollar amounts, limited to two decimal places.

#### The rule that must always hold

`merchantPortion + partnerPortion` must exactly equal `total`.

There is no remainder and no rounding tolerance. A payment that breaks this is rejected with `400 Bad Request`.

`total` must also equal `requestedAmount`. If your integration changes the ticket amount, all four values have to move together.

### Bead's split funding fee

Bead deducts a fee from the withheld partner portion before paying the partner. It is calculated per payment and never touches `merchantPortion`:

```
partnerNet = partnerPortion - splitFundingFee - depositFee
```

`depositFee` is the settlement fee recovered from the partner portion. Both deductions are reported under those names on the distribution summary. See [Split Funding Reports](/split-funding/reports.md).

**There is no standard rate.** The fee is the partner's own contracted rate with Bead, the same rate card that governs their other business, so it differs from partner to partner and can differ per payment method. It resolves from the partner record, not from the merchant's fee configuration, and it cannot be sent on the payment. Your rates are set out in your executed reseller agreement and are also retrievable from the partner fee-schedule endpoint.

The per-payment fee has two components, both deducted from the partner portion:

| Component           | Applied to   |
| ------------------- | ------------ |
| Percentage          | `total`      |
| Per-transaction fee | Each payment |

**The percentage applies to `total`, the full amount the consumer paid.** It is not calculated on `merchantPortion`. The deduction still comes out of the partner portion alone, so the merchant is unaffected either way: a larger total means a larger fee drawn from the withheld amount.

**The fee is calculated at assessment, not at payment creation.** The rate is read as of the payment's capture date, so the result is stable, but the fee is not present on the payment record at transaction time. It is reported afterwards as `splitFundingFee`, on both the transaction report and the distribution summary.

**Rates differ by tender, and that difference is what drives requirement 2 above.** Pull your own fee schedule and compare the cheapest tender you offer against the most expensive one before you design your fee logic. The gap is normally large enough that a single flat consumer fee cannot serve both.

#### Coverage is checked when the payment is created

At payment creation Bead prices every tender the payment page would offer against your contracted rate, and compares each against the partner portion you sent.

* Tenders the partner portion covers are offered on the page.
* Tenders it cannot cover are left off the page, and named on the response.
* If no offered tender is covered, the payment is rejected with `400 Bad Request`. The error prices every offered tender, percentage and per-item fee, so you can resize for the one you want.

The tender is not known at creation, because the consumer selects it on the hosted page. Pricing every candidate tender and narrowing the page is how the check stays exact. You can still narrow `tenderTypes` yourself per payment.

**The creation response names every tender it left off.** `unavailableTenders` is returned on the payment creation response and is empty on an ordinary payment, and on a split funding payment where every candidate tender was covered. Each entry carries:

| Field             | Description                                                                                                    |
| ----------------- | -------------------------------------------------------------------------------------------------------------- |
| `tenderType`      | The tender left off the page.                                                                                  |
| `reason`          | `feeNotCovered` or `noContractedRate`.                                                                         |
| `fee`             | What Bead would have extracted from the partner portion on this tender. Null when there is no contracted rate. |
| `transactionRate` | The percentage rate that was applied. Null when there is no contracted rate.                                   |
| `perItemFee`      | The per-transaction fee that was applied. Null when there is no contracted rate.                               |

Read this on every split funding payment rather than waiting for the distribution. A non-empty array means the consumer saw fewer ways to pay than you intended, and `fee` tells you exactly what the partner portion would have needed to cover.

**A missing contracted rate excludes the tender.** A tender with no rate row for your partner record is priced as uncovered and left off the page, reported as `noContractedRate` with null amounts. It is not treated as free. If you see this reason, the rate is missing from your fee schedule rather than your consumer fee being too small; raise it with your Bead contact.

Equality passes. A partner portion that exactly covers a tender's fee keeps that tender, and a partner on zero rates with a zero per-item fee never loses a tender or receives a rejection, including for a zero partner portion.

**What this check cannot see.** It covers per-payment costs only, the percentage and the per-transaction fee. Settlement fees are charged per settlement event and the number of payments in a settlement is unknown when a payment is created, so settlement fee coverage is not evaluated here. It resolves at distribution assessment instead, described in [Partner distributions](#partner-distributions).

#### Sizing against the floor

Because the per-transaction fee is flat and does not scale with ticket size, low-value tickets need a proportionally larger partner portion for you to earn anything. Settlement fees add a second flat cost that is shared across however many payments land in a settlement.

Where `c` is the consumer fee rate you charge on the merchant's price, `p` is your percentage rate with Bead, `f` is your per-transaction fee and `s` is your settlement fee:

```
flatCostPerPayment         = f + (s / paymentsPerSettlement)
break-even merchantPortion = flatCostPerPayment / (c - p - (p * c))
```

The `p * c` term is there because Bead's percentage is charged on `total`, which includes the consumer fee you added. Sizing against `c - p` alone understates the floor.

**A consumer fee set equal to your Bead rate does not break even.** Because the percentage is charged on the grossed-up total, your fee has to exceed your rate divided by one minus your rate before any flat cost is considered.

**The floor depends on volume, not only on ticket size.** A merchant settling one payment a day carries the whole settlement fee on that payment. The same fee spread across fifty payments is negligible. Model the floor for each merchant against the number of payments they actually put through in a settlement period rather than a single headline figure.

> **Compensation on this traffic is paid to you separately.** Split funding transactions compensate you through the withheld partner portion, paid as its own monthly distribution. The same transactions are not also counted in your standard processing compensation, because the merchant was charged no fee on them and there is nothing there to calculate from. Each transaction is compensated once, through one route or the other. If you move existing traffic onto this program, your compensation on that traffic arrives through the distribution from that point forward. See [Residual Reporting](/settlement/residual-reporting.md).

#### Expect your distribution to differ from what this traffic earned you before

Model this before you move traffic onto the program. On standard processing your compensation derives from fees Bead charged your merchant and reaches you at month end. Here the merchant is charged nothing, so your compensation is the consumer fee you collected, less Bead's fee and the settlement fees, paid as a separate distribution. The two are calculated from entirely different things and will not be the same size. Work it through with your own rates rather than assuming a like for like replacement.

### Worked example

A split funding payment where the merchant keeps less than the full ticket, with the difference withheld for the partner.

| Step                                        | What it represents                                      |
| ------------------------------------------- | ------------------------------------------------------- |
| Consumer pays (`total`)                     | The full ticket amount                                  |
| Merchant is settled (`merchantPortion`)     | The agreed amount, no transaction fee deducted          |
| Withheld for the partner (`partnerPortion`) | `total` minus `merchantPortion`                         |
| Bead's split funding fee                    | Priced on `total`, deducted from the partner portion    |
| Settlement fees                             | Deducted from the partner portion, per settlement event |
| Partner receives (`partnerNet`)             | What remains                                            |

The merchant sees exactly `merchantPortion` on their daily settlement, regardless of what Bead's fee ends up being.

### Collecting a consumer fee alongside this program

**Bead has no consumer fee capability.** There is no fee field on the payment, no rate configuration, and nothing in the API that calculates, displays or collects a consumer fee. Bead can process a fee you have already calculated, folded into the amounts you send. It cannot derive one. Sizing, disclosing and presenting the fee is entirely your own work in your own checkout. The [Consumer Fee Passthrough](/faqs-and-troubleshooting/payments-faqs/consumer-fee-passthrough-for-wallet-and-crypto-tenders.md) page is guidance on how to do that and on the legal considerations. It is not a feature you enable.

The pattern: calculate your consumer fee yourself, per tender, and fold it into `total`. Set `merchantPortion` to the exact price the merchant billed, with nothing deducted. Set the partner portion to the fee amount. The merchant is settled precisely what they billed, with no net due to fees. The withheld amount is paid out to you later, net of Bead's fee and the settlement fees, on the cadence described in [Partner distributions](#partner-distributions).

> **If you use Bead's hosted page for tender selection, read this before you size a fee.** When the consumer chooses their tender on a Bead-hosted page, you do not know the tender at the point you would normally calculate and disclose a tender-specific consumer fee. This program cannot resolve that for you, because the three amounts are fixed when the payment is created. It is also the direct tension with requirement 2 above. Your options are to determine the tender in your own environment before calling Bead, or to size a single fee that covers every tender you offer and accept thinner margin on the cheaper ones. A fee sized for the cheapest tender will leave you underwater on the most expensive one, and the coverage check will drop those tenders from the page. A separate Bead initiative is evaluating consumer fee support for hosted-page flows. It is not part of this program and is not available today.

**Leave headroom.** Sizing a consumer fee to break even against Bead's fee means earning nothing and losing tenders from the page on any rounding. Size for the most expensive tender you support, or size per tender.

### Before you start

A merchant must be enrolled before it can accept a split funding block on a payment. Enrollment is a reviewed change to the merchant record, submitted and approved through [Update Merchant](/entity-management/merchant-management/update-merchant.md).

There is no field for this on merchant application submission. A merchant must be boarded first, then enrolled with the update-request call below. Nothing stops you from submitting the enrollment request immediately after boarding completes, since it is a partner-self-service call, but it is always a separate second step.

Use a partner API key. You can enroll any merchant in your own hierarchy, and you can approve your own request. Terminal API keys cannot make this change and return `403 Forbidden`.

**Step 1. Request the change.** Note the request id in the response.

```json
POST /Merchants/{merchantId}/update-requests

{
  "submit": true,
  "precedence": 100,
  "justification": "Enrolling in the split funding program",
  "expiresAt": "2026-12-31T23:59:59Z",
  "changes": {
    "setSplitFundingEnabled": true
  }
}
```

**Step 2. Approve it.** The change applies immediately on approval.

```json
POST /Merchants/{merchantId}/update-requests/{requestId}/approve

{
  "reason": "Approved for split funding program"
}
```

**Step 3. Confirm.** [Get Merchant](/entity-management/merchant-management/get-merchant.md) returns the enrollment flag as `isSplitFundingEnabled`, on the flat `merchant` node of the response rather than inside `details`. It reads `true` once the change has applied.

> **The old field names are not aliased.** `setRebateProgramEnabled` and `isRebateProgramEnabled` were renamed to `setSplitFundingEnabled` and `isSplitFundingEnabled`. There is no "Program" in either new name. A request that still sends `setRebateProgramEnabled` is dropped by the deserializer and returns a successful `200` with nothing enabled, so step 3 is the only reliable confirmation that enrollment applied.

To remove a merchant from the program, send the same request with the flag set to `false`. That stops new split funding payments. Anything already taken still pays out to the partner as normal, and in-flight settlements and assessed distributions are unaffected.

> **`expiresAt` does two different things here, and neither is the one integrators expect.**
>
> It does not time box the enrollment. Setting `expiresAt` on the update request does not revert the flag. Use an explicit `false` request to remove a merchant from the program.
>
> Omitting it blocks your later requests. The overlap check considers only `approved` and `applied` requests, and treats a null `expiresAt` as an open-ended window. A second request at the same `precedence` therefore returns `409 Conflict` indefinitely, and that includes the `false` request above. Set an `expiresAt` on every enrollment request, or submit the later request at a higher `precedence`.

Separately, confirm the partner payout setup described in [Partner distributions](#partner-distributions) before the first split funding payment is taken. That setup is not part of enrollment and is not validated here.

### Creating a split funding payment

Add a `splitFunding` object to the normal payment creation request. The endpoint and all other fields are unchanged.

> **`rebate` is no longer accepted, and sending it fails silently.** `splitFunding` is the only name the request binds. A request that still sends `rebate` returns `200 OK` with the payment created as an ordinary payment: the field is dropped, nothing is withheld for the partner, and no error is returned. There is no way to detect this from the response. If your integration predates the rename, switch it to `splitFunding` and confirm against a [Split Funding Reports](/split-funding/reports.md) transaction row, where a genuine split funding payment shows a `partnerPortion` greater than zero. Inside the wrapper the amount field is `partnerPortion` only, with no `targetRebate` alias.

Endpoint:

```http
POST https://api.test.devs.beadpay.io/Payments
```

`POST /Payments/crypto` is deprecated but still supported and accepts the same body, including `splitFunding`. Use `POST /Payments` for new work.

Headers:

```http
X-Api-Key: {apiKey}
Content-Type: application/json
Accept: application/json
```

Request body:

```json
{
  "terminalId": "TERM-123",
  "merchantId": "MERCH-456",
  "requestedAmount": 100.00,
  "reference": "ORDER-4821",
  "splitFunding": {
    "total": 100.00,
    "merchantPortion": 90.00,
    "partnerPortion": 10.00
  }
}
```

The response is the standard payment creation response, plus `unavailableTenders`. See [Create Payment](/payments/create-payment.md) for the full shape and for the terminal type rules that also apply to split funding payments, including the `customer` and `refundEmail` requirements on virtual terminals.

#### Field reference

`splitFunding` is an optional object. It is only accepted for enrolled merchants. Omit it entirely for a standard payment.

`splitFunding.total` is the total amount the consumer pays. Must exactly equal `requestedAmount`. It is also the base Bead's percentage is charged on.

`splitFunding.merchantPortion` is the exact amount to settle to the merchant daily. Settled in full with no transaction fee deducted.

`splitFunding.partnerPortion` is the amount withheld at settlement for later distribution to the partner. Must exactly equal `total` minus `merchantPortion`.

### Why a split funding payment is rejected

All of the following return `400 Bad Request`.

| Condition                                                      | What to check                                                                                  |
| -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `merchantPortion + partnerPortion` does not equal `total`      | The core rule. Look for a rounding error, for example `90.00 + 9.99` against a `100.00` total. |
| The partner portion covers no offered tender                   | The coverage check. The error prices every offered tender so you can resize.                   |
| `total` does not equal `requestedAmount`                       | Usually the ticket amount changed and only one of the two values was updated.                  |
| Only one or two of the three amounts sent                      | All or nothing. Send all three, or omit the object entirely.                                   |
| A split funding block sent for a merchant that is not enrolled | Confirm the enrollment flag on the merchant record.                                            |
| `merchantPortion` greater than `total`                         | The values are most likely transposed.                                                         |
| More than two decimal places on any amount                     | Often a percentage calculated on your side and not rounded before sending.                     |

Sending `rebate` instead of `splitFunding` is not on this list, because it is not rejected. See the callout in [Creating a split funding payment](#creating-a-split-funding-payment).

If you calculate `merchantPortion` or the partner portion from a percentage, round to two decimals and then derive the third value by subtraction rather than by a second percentage calculation. Deriving both independently is the most common cause of a failed identity check.

> **Error responses on this endpoint are not uniform, and two of them are bare strings.** Most validation failures return the standard error body, but both the enrollment check and the fee coverage rejection return a plain text message at `text/plain` rather than the structured error shape the endpoint declares. Match on the HTTP status rather than on the response shape, and log the body. The coverage rejection's message is your only diagnostic for resizing the partner portion, so a client that discards a body it cannot parse as JSON is left with a `400` and no detail.

#### A quote for a tender that was not offered

A tender dropped from the page by the coverage check is also refused at quote time. Request-quote and pending-transaction return `409 Conflict` with `TENDER_NOT_REQUESTED`. This is what makes the narrowed page binding for direct API callers as well as for the hosted page.

#### What is not returned

The amounts you send are not echoed back on the payment creation response, the payment status endpoints, or [Payment Statuses](/payments/payment-statuses.md) tracking. Bead's fee is not returned on any payment level response either.

The creation response does report which tenders were left off the page, in `unavailableTenders`, but it does not list the tenders that were offered.

The amounts do appear on the refund validation responses, under the older `rebate` and `targetRebate` names. No Bead tender supports refunds today, so this does not arise in practice.

Keep your own record of what you sent. To see the amounts and the fee after the fact, use the [Reporting](#reporting) endpoints below.

Payment webhooks are unchanged for split funding payments, and partner distributions do not emit webhooks.

### Settlement behavior

* The merchant is settled `merchantPortion` on the normal daily cycle, with no transaction fee.
* Nothing is billed back to the merchant later. Collection happens by withholding at settlement.

How the per-deposit settlement fee is handled depends on the composition of that day's settlement.

| Settlement composition                       | Merchant's deposit        | Recovered from the partner portion |
| -------------------------------------------- | ------------------------- | ---------------------------------- |
| Every payment is a split funding payment     | Full net, no fee deducted | Yes, one fee per settlement event  |
| A mix of split funding and ordinary payments | Fee deducted as usual     | No                                 |
| No split funding payments                    | Fee deducted as usual     | Not applicable                     |

**On a split-funding-only day the merchant receives their portion exactly**, with no fee-schedule lookup on the deposit at all. Neither a missing fee schedule nor a below-fee hold can delay that merchant's money.

**On a mixed day the deposit is charged on the ordinary rules**, and nothing is recovered from the partner portion for it. If your merchant also takes ordinary payments, be precise with them about this: the exact-settlement outcome applies to days where their settlement holds split funding payments alone.

The fee is charged once per settlement event, not once per payment, and not once per transfer when a daily deposit limit splits a deposit into several transfers.

The settlement and batch reports carry two informational fields for split funding activity:

| Field                          | Description                                                                          |
| ------------------------------ | ------------------------------------------------------------------------------------ |
| `partnerPortion`               | Sum of the partner portion across split funding payments in the settlement or batch. |
| `splitFundingTransactionCount` | Number of split funding payments in the settlement or batch.                         |

**Both fields sit on the settlement and batch report rows, not on the settlement or batch records themselves.** The settlement and batch responses returned by the endpoints on [Settlements](/settlement/settlements.md) and [Batches](/settlement/batches.md) do not carry either field. Read them from the settlement and batch reports, where they are also available as selectable CSV columns. Merchants with no split funding activity show zero.

These are aggregates for visibility. They are not the basis of the partner payout. See the caution in [Residual Reporting](/settlement/residual-reporting.md).

### Partner distributions

The withheld partner portion is paid to the partner as a single periodic bank transfer covering all of that partner's merchants together, not one payment per merchant or per transaction. It is sent to the partner account on file described in [Two destinations, fixed by role](#two-destinations-fixed-by-role), and it is a separate payment from any standard processing compensation you receive from Bead.

* The amount is the sum of the partner portion across every qualifying payment in the run, less the per payment fee and the settlement fees.
* Distributions to the partner account run monthly.

**Settlement fee coverage resolves here, not at payment creation.** A distribution whose total partner net is not positive is created directly into `blocked`, alerted internally, and never paid until an operator resolves it. The payout step re-checks the payable amount as a safety net.

Four things must be in place before a partner can be paid, and none of them are checked at enrollment. They are checked when the payout runs, which means a gap here surfaces at the first payout rather than at setup:

1. The partner has a designated representing merchant record, which is where the funds are sent and where the partner's contracted rates are read from.
2. That merchant has complete bank details, with an account type of `Checking` or `Savings`.
3. That merchant has fee rules for every payment method the enrolled merchants will use. Bead's fee is read per payment method, so a payment on a method with no configured rate cannot be priced, and that tender is left off the payment page at creation.
4. That merchant is active.

Confirm all four with your Bead contact before the first split funding payment is taken.

#### Refunds (reserved)

No Bead tender currently supports a refund, so this does not come up in practice today. The behavior below is defined for when a tender that supports refunds is added, or another refund-like event occurs:

* A split funding payment that is refunded, in full or in part, before the partner payout would be excluded from that payout automatically.
* A refund that lands after the payout has gone out would be corrected on the partner's next distribution.
* A refund returns the full amount the consumer paid, which is `total`, not `merchantPortion`. If that amount included a consumer fee, the consumer is made whole for the fee as well, and recovering it is a matter between you and your merchant.

### Reporting

Two report families cover split funding activity. Both support pagination, sorting, and column selectable CSV export, and both are callable with your partner API key for your own partner or any partner beneath it. See [Split Funding Reports](/split-funding/reports.md) for the full reference.

These reports are the only place the amounts and Bead's fee are readable after payment creation.

#### Distribution status values

`status` and `blockedReason` are both partner readable. They are returned on the base distribution summary report, on a separate top level `distributions[]` array rather than on the per merchant rows, and they do not appear on the period summary, the account summary or the CSV. See [Split Funding Reports](/split-funding/reports.md) for where they sit in the response.

| Status      | Meaning                                          |
| ----------- | ------------------------------------------------ |
| `assessed`  | Calculated and awaiting payout.                  |
| `paying`    | Payout in progress.                              |
| `paid`      | Paid to the partner.                             |
| `blocked`   | Held for Bead review. Not retried automatically. |
| `cancelled` | Voided.                                          |

A distribution is held at `blocked` rather than paid when something about the period or the payout account prevents it. The usual causes are a partner net for the period that is not positive, which is the check that covers settlement fee shortfalls that the creation-time coverage check cannot see, or a partner account on file that is not ready to receive funds, for example a missing or inactive representing merchant record, incomplete bank details, or an unsupported bank account type. See [Two destinations, fixed by role](#two-destinations-fixed-by-role) for what the payout account has to be.

`blockedReason` accompanies `status` on the same `distributions[]` array and names the specific check that held the distribution. There are eight values. Five of them describe the period's arithmetic or the payout account on file:

| Reason                         | Meaning                                                                                                                                                  |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `partnerNetNotPositive`        | The distribution as a whole netted to zero or less. This is the check that covers settlement fee shortfalls the creation-time coverage check cannot see. |
| `representingMerchantNotFound` | No designated representing merchant record was found for the partner, so there is no account to send funds to.                                           |
| `representingMerchantInactive` | The representing merchant record is not active.                                                                                                          |
| `missingBankDetails`           | The representing merchant record does not carry complete bank details.                                                                                   |
| `unsupportedBankAccountType`   | The bank account on file is not an account type the payout supports. The supported types are `Checking` and `Savings`.                                   |

The three `representingMerchant` reasons and `missingBankDetails` all say the same thing in different ways: the partner account on file is not ready to receive funds.

The remaining three values, `originationRejected`, `originationAmbiguous` and `payoutReturned`, are reported against the payout transfer itself rather than against the period's arithmetic or the account record.

If a distribution is blocked, contact your Bead integration contact. Blocked distributions are not retried automatically.

### Troubleshooting

**A payment is rejected with `400`** Work through the table in [Why a split funding payment is rejected](#why-a-split-funding-payment-is-rejected). The identity check, the coverage check and the `total` versus `requestedAmount` check account for most cases.

**Tenders are missing from the payment page** Read `unavailableTenders` on the creation response. It names each tender and why: `feeNotCovered` means the partner portion did not cover Bead's fee on that tender, and `fee` tells you what it would have needed; `noContractedRate` means your fee schedule has no rate for it. Rates differ substantially by tender, which is why a single flat consumer fee rarely works. See [Coverage is checked when the payment is created](#coverage-is-checked-when-the-payment-is-created).

**A quote returns `409 TENDER_NOT_REQUESTED`** The tender was not on the page for that payment, either because you narrowed `tenderTypes` yourself or because the coverage check dropped it.

**An enrollment request returns `409 Conflict`** An earlier `approved` or `applied` update request with no `expiresAt` is treated as covering an open-ended window, so any later request at the same `precedence` conflicts with it indefinitely. This includes the `setSplitFundingEnabled: false` request that would remove the merchant from the program. Set an `expiresAt` on every enrollment request, or submit the later one at a higher `precedence`. See [Update Merchant](/entity-management/merchant-management/update-merchant.md).

**Enrollment returned `200` but nothing is enabled** Check the field name you sent. The old `setRebateProgramEnabled` is not aliased to `setSplitFundingEnabled`, and an unrecognized field is dropped by the deserializer rather than rejected, so the request still returns `200`. Read the merchant back and check `isSplitFundingEnabled` on the flat `merchant` node.

**The payment succeeded but nothing was withheld** Check the wrapper name. `rebate` is no longer bound and is dropped silently, so the payment is created as an ordinary one with a `200`. Confirm the request sends `splitFunding`, then check a [transaction report](/split-funding/reports.md) row for the payment: a genuine split funding payment shows a `partnerPortion` greater than zero.

**`splitFundingFee` or `partnerNet` is null on the transaction report** No rate resolved for that payment's tender, which is the same condition that defers the payment at distribution assessment. `partnerNet` is null whenever the fee is. Raise the missing rate with your Bead contact.

**The merchant's settlement does not match `merchantPortion`** Confirm the payment carried a split funding block and that the merchant was enrolled at the time of creation. A payment created before enrollment is processed as a standard payment. If the settlement mixed split funding and ordinary payments, the deposit carried the settlement fee on the ordinary rules; see [Settlement behavior](#settlement-behavior). Check the [transaction report](/split-funding/reports.md) for the payment to see the amounts as they were recorded.

**The merchant is not getting a deposit at all** Check what the merchant portion was set to. If it is set at or near the full ticket with no consumer fee added on top, there is nothing left to cover Bead's costs, and those payments will have been rejected or had their tenders removed at creation. See [Where the money for Bead's fee comes from](#where-the-money-for-beads-fee-comes-from).

**Enrollment returns `403`** You are using a terminal API key. Enrollment requires a partner API key with the merchant in its hierarchy.

**A partner has not been paid when expected** Check the four prerequisites in [Partner distributions](#partner-distributions) first. A missing representing merchant, incomplete bank details, or an inactive merchant record are the most common causes, and none of them fail at enrollment. Then check whether the distribution is `blocked` and read its `blockedReason` on the `distributions[]` array, and if it is blocked, contact your Bead integration contact.

**We want the partner portion to go somewhere else** It cannot. The two destinations are fixed by role and are not settable on a payment. See [Two destinations, fixed by role](#two-destinations-fixed-by-role).

### Next steps

* [Consumer Fee Passthrough for Wallet and Crypto Tenders](/faqs-and-troubleshooting/payments-faqs/consumer-fee-passthrough-for-wallet-and-crypto-tenders.md), which you should read before building against this page
* [Create Payment](/payments/create-payment.md) for the full payment creation contract
* [Split Funding Reports](/split-funding/reports.md) for transaction detail and partner distribution reconciliation
* [Settlements](/settlement/settlements.md) and [Residual Reporting](/settlement/residual-reporting.md) for reconciliation
* [Update Merchant](/entity-management/merchant-management/update-merchant.md) for the enrollment change


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.bead.xyz/split-funding.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.