---
name: split-a-payment
description: Split payments across multiple recipients with the Fynex Payments API. Use when the user wants to split a payment, divide a charge between a platform and its sellers, take a marketplace commission or platform fee out of a customer payment, do revenue sharing, or send part of one charge to a vendor. Covers percentage and fixed splits, where the platform fee comes from, what happens on a refund, and why there is no separate transfer call.
---

# Split a payment with Fynex

A split is declared **on the payment that collects the money**, not sent afterwards.
There is no transfer endpoint and no second call: put `orderData.payeeDistribution`
on the create request and the funds land already divided — **provided the seller has
an active split rule** (`GET /payments-api/v1/split-rules/active`). With no active rule
the distribution is ignored and the payment settles unsplit; an `absolute`-mode rule
takes the shares from its own lines and ignores the distribution entirely.

## Before you start

- A seller secret key from the dashboard: [/keys](/keys). One key covers Payments and Billing.
- At least one **payee** — whoever receives a share. See the `onboard-sellers` skill.
- Test with an `sk_test_` key, on the same paths: it is test mode wherever it is sent.

## The shape

`orderData.payeeDistribution` is a list of shares, one per payee, in integer minor units:
`{ "payeeId": 101, "amountMinor": 8500 }`. The shares must add up to the payment (`10000`
for 100.00), or the request is refused with `400` — which is also what catches a share
sent in the wrong unit. Your commission is not a line of its own: it is the split rule's
fee, withheld from each share (`percentBps` / `fixedAmountMinor` on the rule or its lines).
With an `absolute`-mode rule the shares come from the rule and whatever its lines leave
over stays with you too.

Both hosted checkout and the server-to-server flow accept it:

- `POST /payments-api/v1/checkout` — you redirect the buyer, lowest PCI scope
- `POST /payments-api/v1/initialize-payment` then `POST /payments-api/v1/finalize-payment` —
  you handle card data

## Rules that bite

- **Units.** The payment's own `amount` is MAJOR units (`49.99`); each share's
  `amountMinor` is integer minor units (`4999`). The share's major-units `amount` still
  works but is deprecated, and one distribution must not mix the two.
- **Idempotency-Key is required on the payment operations** (checkout, initialize,
  finalize, capture, refund, refund cancel). One key covers a whole initialize + finalize pair; reuse it
  across the two rather than minting a second.
- **The split happens at settlement, once.** Payees' shares land in their wallets under a
  T+N business-day hold before they can be paid out.
- **A refund does not unwind the split by itself.** Fynex works out what each party gives
  back — the refunded fraction of what it received — and finance reverses it. Tell the user
  so; do not promise an automatic reversal.
- **A `200` is not a successful payment.** Read `status`, and when it is `failed` read
  `failureCode` — every value is enumerated in the spec with whether a retry can succeed.

Everything else — rounding, fees, over-allocation, minimums, the remainder, holds,
refunds and chargebacks, each with a worked example — is in one place: the Splits guide,
section *How Fynex splits money*.

## Read next

- [Splits guide](/payments-api/v2/docs/splits.md)
- [Hosted checkout](/payments-api/v2/docs/hosted-checkout.md) · [Server-to-server](/payments-api/v2/docs/server-to-server.md)
- [OpenAPI document](/payments-api/v2/openapi.json) — generate a client from this
- [Agent index](/payments-api/v2/llms.txt)