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 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.

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.

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

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

3. Confirm

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.

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

{
  "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 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.

What this page does not cover

Read the Split Funding page in full before you build. In particular:

• What this program requires of you, four obligations that sit with you rather than with Bead

• Two destinations, fixed by role, why you cannot name a payee

• Consumer Fee Passthrough, the legal and per-tender considerations

• Split funding and residuals are mutually exclusive on the same traffic

Related

• Split Funding

• Split Funding Reports

• Create Payment

• Update Merchant