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.
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 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.
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.
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.
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. 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:
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.
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:
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.
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:
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:
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.
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:
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.
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.
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 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.
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.
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.
Step 2. Approve it. The change applies immediately on approval.
Step 3. Confirm. Get Merchant 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.
setRebateProgramEnabledandisRebateProgramEnabledwere renamed tosetSplitFundingEnabledandisSplitFundingEnabled. There is no "Program" in either new name. A request that still sendssetRebateProgramEnabledis dropped by the deserializer and returns a successful200with 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.
expiresAtdoes two different things here, and neither is the one integrators expect.It does not time box the enrollment. Setting
expiresAton the update request does not revert the flag. Use an explicitfalserequest to remove a merchant from the program.Omitting it blocks your later requests. The overlap check considers only
approvedandappliedrequests, and treats a nullexpiresAtas an open-ended window. A second request at the sameprecedencetherefore returns409 Conflictindefinitely, and that includes thefalserequest above. Set anexpiresAton every enrollment request, or submit the later request at a higherprecedence.
Separately, confirm the partner payout setup described in 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.
rebateis no longer accepted, and sending it fails silently.splitFundingis the only name the request binds. A request that still sendsrebatereturns200 OKwith 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 tosplitFundingand confirm against a Split Funding Reports transaction row, where a genuine split funding payment shows apartnerPortiongreater than zero. Inside the wrapper the amount field ispartnerPortiononly, with notargetRebatealias.
Endpoint:
POST /Payments/crypto is deprecated but still supported and accepts the same body, including splitFunding. Use POST /Payments for new work.
Headers:
Request body:
The response is the standard payment creation response, plus unavailableTenders. See Create Payment 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.
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.
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/plainrather 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 a400and 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 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 endpoints below.
Payment webhooks are unchanged for split funding payments, and partner distributions do not emit webhooks.
Settlement behavior
The merchant is settled
merchantPortionon 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.
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:
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 and Batches 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.
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, 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:
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.
That merchant has complete bank details, with an account type of
CheckingorSavings.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.
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, notmerchantPortion. 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 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 for where they sit in the response.
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 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:
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. 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.
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.
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 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. Check the transaction report 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.
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 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.
Next steps
Consumer Fee Passthrough for Wallet and Crypto Tenders, which you should read before building against this page
Create Payment for the full payment creation contract
Split Funding Reports for transaction detail and partner distribution reconciliation
Settlements and Residual Reporting for reconciliation
Update Merchant for the enrollment change
Last updated