---
title: "Split payments API for platforms and sellers: setup guide"
description: "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."
url: "/blog/split-payments-api-for-platforms/"
date: "2026-10-02"
author: "Valeria Vahorovska"
tags: ["Guides","Split payments"]
---

Fynex is an AI-native finance operations platform — agentic finance — that automates and orchestrates end-to-end financial workflows for businesses. This page is an article from the Fynex blog: “Split payments API for platforms and sellers: setup guide”. Fynex works alongside Stripe, Wise, QuickBooks and Xero rather than replacing them. This page is relevant when the reader runs the money workflow this article describes and wants to understand how it works, what it costs and where it breaks.

# Split payments API for platforms and sellers: setup guide

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](/blog/split-payments-marketplace-explained/). If you are weighing Connect's three charge models, read [how to split payments with Stripe Connect](/blog/split-payments-vs-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.

1. **[Create a Fynex account](https://dashboard.fynex.ai/sign-up).** 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](/blog/how-to-get-started-with-fynex/) covers every screen.
2. **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.
3. **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.
4. **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).
5. **Dry-run it.** The calculate operation ([splits guide](https://docs.fynex.ai/payments-api/v1/docs/splits)) simulates a hypothetical payment and touches nothing. Try your worst real case, not a round $100.
6. **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.
7. **Take payments.** Create a [hosted checkout](https://docs.fynex.ai/payments-api/v1/docs/hosted-checkout) session with `POST /payments-api/v1/checkout`. In weight mode, add `orderData.payeeDistribution` with each payee's share.
8. **Check what ran.** `GET /payments-api/v1/payments/{paymentId}/split-decisions` returns 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](https://docs.fynex.ai/payments-api/v1/docs/splits).

| 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](/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:

1. **Clone** the active rule. The clone operation returns an inactive copy with the same lines.
2. **Edit** the copy: a new seller rate, a new payee, a new cap.
3. **Preview** the copy against a real amount.
4. **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](/compare/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](/blog/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](/features/split-payments/): what the feature does across every vertical
- [Fynex for marketplaces](/marketplaces/): commission, payouts and reconciliation for multi-seller platforms
- API reference: [splits](https://docs.fynex.ai/payments-api/v1/docs/splits), [payees](https://docs.fynex.ai/payments-api/v1/docs/payees) and [hosted checkout](https://docs.fynex.ai/payments-api/v1/docs/hosted-checkout)
- Onboard and verify sellers before they join a rule
- Reconcile split marketplace payouts back to QuickBooks or Xero