Split payments API for platforms and sellers: setup guide
How to split payments between a platform and its sellers with the Fynex API: add payees, build a versioned split rule, preview it, activate it.
To split payments between your platform and its sellers on Fynex, add each seller as a payee, create a split rule holding your commission and each payee’s share, preview it against a real amount, then activate it. From then on every settled payment divides automatically, and each split records the rule version that ran.
This guide is for marketplace and platform teams choosing, or wiring, a split payments API. It covers the setup steps, the rule’s fields, how to change terms without a release, and how the model differs from Stripe Connect. If you are still learning how a marketplace split works, start with split payments in a marketplace explained. If you are weighing Connect’s three charge models, read how to split payments with Stripe Connect.
How to set up split payments on Fynex: the steps
Eight steps take you from an empty account to a live split. Steps 2 to 6 work the same in the dashboard and over the API, which enforces the same create, preview and activate order.
- Create a Fynex account. The setup dock walks you through a first payee, a commission rule, an invoice and a test payment. You can explore in sandbox before verification. The getting-started guide covers every screen.
- Add each seller as a payee. Enter business name, email, role, tax ID, address and bank details, or use a sample payee. Over the API,
POST /payments-api/v1/payees. A wallet for receiving funds is created automatically. - Choose how the split is decided. Absolute mode: the rule’s lines decide every payment the same way. Weight mode (the default): each payment says how it divides, and the rule adds the fee policy.
- Set your commission. Pick Fixed platform fee (one fee for every payee: a percentage, a flat dollar amount, or both) or Custom per-payee allocation (each payee’s line carries its own fee).
- Dry-run it. The calculate operation (splits guide) simulates a hypothetical payment and touches nothing. Try your worst real case, not a round $100.
- Preview and activate. The preview returns each payee’s gross share, fee and net, plus an activation receipt valid for 10 minutes. In the dashboard, Save and activate rule. Over the API, the activate operation takes the receipt and an explicit confirmation.
- Take payments. Create a hosted checkout session with
POST /payments-api/v1/checkout. In weight mode, addorderData.payeeDistributionwith each payee’s share. - Check what ran.
GET /payments-api/v1/payments/{paymentId}/split-decisionsreturns the decision record for any payment.
What does a Fynex split rule contain?
A split rule is one object that holds the whole allocation: who is paid, how much, what fee you keep, and what happens to anything left over. Every field below is documented under the splits tag.
| Field | What it decides |
|---|---|
allocationMode | absolute (the rule’s lines decide) or weight (the payment’s payeeDistribution decides) |
type | fixed (one fee for every payee) or custom (a fee per line) |
lines | One per payee: a percentage share, a fixed share, or both, plus optional minimum and maximum |
remainderPolicy | Where unallocated money goes: your main wallet or a remainder wallet |
overAllocationPolicy | What happens if lines claim more than the amount: fail, cap by priority, or scale down |
effectiveFrom / effectiveTo | When the rule applies |
version | Recorded on every split, so a past payment stays explainable |
All split arithmetic runs in integer minor units: 10000 is $100.00. The preview, the dry run and the live split use the same calculation, so they always round the same way. Model a split before you build it with the split payment calculator.
How do you change a split rule without a release?
You change terms by activating a new rule version, not by shipping code. An active rule is never edited in place. That keeps every past payment tied to the terms that were in force when it settled.
The sequence is four moves:
- Clone the active rule. The clone operation returns an inactive copy with the same lines.
- Edit the copy: a new seller rate, a new payee, a new cap.
- Preview the copy against a real amount.
- Activate it. Activation is an atomic swap: the old rule stands down in the same transaction.
There is only ever one active rule per account, and never a gap between two rules unless you schedule one. A payee must be active to sit on a rule, so an archived seller cannot silently receive a share. When a seller disputes a payout months later, the decision record names the rule version, the lines that fired and the reason any line did not.
How does this compare to Stripe Connect’s split model?
Stripe Connect hands you charge-level primitives; Fynex holds the split as a rule. Connect is strong for one payment, one connected seller and a flat platform fee. The difference shows when one payment pays several parties or commission terms change often. Fynex vs Stripe Connect sets the two side by side.
| Question | Fynex | Stripe Connect |
|---|---|---|
| Where the commission lives | A versioned split rule with per-payee terms | An application_fee_amount your code sets per charge |
| One payment, several recipients | Several lines on one rule | Separate charges and transfers, one transfer per recipient |
| Changing a seller’s rate | Clone, preview, activate from the dashboard | Change the fee calculation in your application |
| Explaining a past split | Decision record with the rule version that ran | Rebuilt from your application’s records |
| Where the money lands | Each payee’s wallet, then a payout to their bank | The connected account’s Stripe balance |
Many teams keep their card acceptance and add Fynex as the layer that runs the split, the payouts and the reconciliation. Alternatives to Stripe Connect covers the wider field.
What happens to fees, remainders and refunds?
A split runs once, when the payment’s money settles to your main wallet. It divides the settled amount, moves each payee’s net share into that payee’s wallet, and records the split. Nothing is left unaccounted for.
- Fees you withhold from each share go to your own operational wallet.
- Remainder: whatever absolute-mode lines leave unallocated stays in your main wallet, or moves to a remainder wallet you name.
- Holds: each share lands under a maturity hold and becomes payable after a set number of business days. Three by default.
- Refunds and lost chargebacks: Fynex computes a pro-rata plan, so every party gives back the same fraction the buyer got back. The plan is reviewed before any money moves, and no payee wallet is ever driven negative.
This is agentic finance applied to the split: the rule does the arithmetic on every payment, and every step that moves money waits for approval. You run the marketplace, not the spreadsheet. Once shares land, paying out sellers and service providers is the next step.
Where to go next
- Split payments on Fynex: what the feature does across every vertical
- Fynex for marketplaces: commission, payouts and reconciliation for multi-seller platforms
- API reference: splits, payees and hosted checkout
- Onboard and verify sellers before they join a rule
- Reconcile split marketplace payouts back to QuickBooks or Xero