> 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/enable-and-send-a-split-funding-payment.md). # Enable and Send a Split Funding Payment Four calls, end to end. This page is the short path for a developer who already knows what the program is and wants to get a split funding payment through. For the rules, the obligations and the arithmetic behind the amounts, read [Split Funding](/split-funding.md) first. Use a **partner API key** for calls 1 to 3 and the **terminal API key** for call 4. A terminal key cannot enroll a merchant and returns `403 Forbidden`. ## The four calls | # | Call | Key | What it does | | - | ------------------------------------------------------------------ | -------- | ----------------------------------------------- | | 1 | `POST /Merchants/{merchantId}/update-requests` | Partner | Requests enrollment | | 2 | `POST /Merchants/{merchantId}/update-requests/{requestId}/approve` | Partner | Applies it immediately | | 3 | `GET /Merchants/{merchantId}` | Partner | Confirms `isSplitFundingEnabled` is `true` | | 4 | `POST /Payments` | Terminal | Creates the payment with a `splitFunding` block | Calls 1 to 3 are one-time per merchant. Call 4 is every payment. `POST /Payments/crypto` is deprecated but still supported and accepts the same body, including `splitFunding`. Use `POST /Payments` for new work. ## 1. Request enrollment Always set `expiresAt`. Omitting it leaves an open-ended window that makes every later request at the same `precedence` fail with `409 Conflict`, including the request that would later remove the merchant from the program. ```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 } } ``` Keep the request id from the response. ## 2. Approve it You can approve your own request for any merchant in your hierarchy. The change applies on approval. ```json POST /Merchants/{merchantId}/update-requests/{requestId}/approve { "reason": "Approved for split funding program" } ``` ## 3. Confirm ```http GET /Merchants/{merchantId} ``` Read `isSplitFundingEnabled` on the flat `merchant` node of the response, not inside `details`. It reads `true` once the change has applied. **Do not skip this call.** The old field name `setRebateProgramEnabled` is not aliased. A request that still sends it is dropped by the deserializer and returns a successful `200` with nothing enabled, so the response to call 1 does not tell you whether enrollment worked. Step 3 is the only reliable confirmation. ## 4. Create the payment Add a `splitFunding` block to an ordinary payment request. Everything else about the request is unchanged. ```json POST /Payments { "terminalId": "TERM-123", "merchantId": "MERCH-456", "requestedAmount": 103.50, "reference": "ORDER-4821", "splitFunding": { "total": 103.50, "merchantPortion": 100.00, "partnerPortion": 3.50 } } ``` In this shape the merchant billed $100.00, you added a $3.50 consumer fee, and the merchant is settled $100.00 exactly. The $3.50 is withheld and paid to you later, net of Bead's fee. ### The three rules the amounts must satisfy 1. `merchantPortion + partnerPortion` equals `total`, exactly. No rounding tolerance. 2. `total` equals `requestedAmount`. 3. The partner portion covers Bead's fee on at least one offered tender, or the payment is rejected. If you calculate one portion from a percentage, round it to two decimals and derive the other by subtraction. Calculating both independently is the most common cause of a failed balance check. ## Then read the response ```json { "paymentId": "pay_c10b29e3c4b54d8aa12f9934", "trackingId": "c10b29e3c4b54d8aa12f9934", "paymentPageId": "6539fa89f0363f1722b377ef", "paymentUrls": ["https://pay.test.devs.beadpay.io/6539fa89f0363f1722b377ef"], "unavailableTenders": [] } ``` **Check `unavailableTenders` before you present the page.** A non-empty array means the consumer will see fewer ways to pay than you intended. Each entry carries `tenderType`, `reason`, `fee`, `transactionRate` and `perItemFee`. * `feeNotCovered`, the partner portion was smaller than Bead's fee on that tender. `fee` tells you what it needed to be. * `noContractedRate`, your fee schedule has no rate for that tender. A configuration gap, not a sizing problem. Raise it with your Bead contact. ## Three things that fail silently These are the ones that cost integrators the most time, because none of them returns an error. | What happens | Why | How to catch it | | -------------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- | | Enrollment returns `200`, nothing is enabled | You sent `setRebateProgramEnabled`, which is no longer bound | Call 3 | | Payment returns `200`, nothing is withheld | You sent `rebate` instead of `splitFunding`, which is dropped | A [Split Funding Reports](/split-funding/reports.md) row showing `partnerPortion` greater than zero | | Consumer sees fewer tenders than expected | The partner portion did not cover Bead's fee on the rest | `unavailableTenders` on the creation response | ## Sizing the partner portion Bead's fee is the contracted tender rate applied to `total`, the full amount the consumer paid, plus the per-item fee. Both come out of the partner portion. Because the rate is charged on the total rather than on the merchant's price, a consumer fee set equal to your Bead rate does not break even. The percentage your fee has to exceed is your rate divided by one minus your rate. Rates also differ sharply between tenders, so a single flat fee across every tender will be underwater on the expensive ones. Full detail, including the volume-dependent floor on small tickets, is in [Sizing against the floor](/split-funding.md#sizing-against-the-floor). ## What this page does not cover Read the [Split Funding](/split-funding.md) page in full before you build. In particular: * [What this program requires of you](/split-funding.md#what-this-program-requires-of-you), four obligations that sit with you rather than with Bead * [Two destinations, fixed by role](/split-funding.md#two-destinations-fixed-by-role), why you cannot name a payee * [Consumer Fee Passthrough](/faqs-and-troubleshooting/payments-faqs/consumer-fee-passthrough-for-wallet-and-crypto-tenders.md), the legal and per-tender considerations * Split funding and residuals are mutually exclusive on the same traffic ## Related * [Split Funding](/split-funding.md) * [Split Funding Reports](/split-funding/reports.md) * [Create Payment](/payments/create-payment.md) * [Update Merchant](/entity-management/merchant-management/update-merchant.md) --- # 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/enable-and-send-a-split-funding-payment.md?ask=&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.