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

## 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 work goes to `https://staging-api.fynex.ai`, same paths. An `sk_test_` key is
  test mode wherever it is sent.

## The shape

`orderData.payeeDistribution` is a list of shares. Each entry names a payee and how much
of this payment is theirs. Whatever is not distributed stays with you — that is your
commission; you do not add a line for yourself.

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 are not uniform.** Checkout takes MAJOR units (`49.99`); payouts take minor
  units (`4999`). Read the field name every time — neither rejects the wrong one, so a
  guess is wrong by a factor of a hundred and nothing errors.
- **Idempotency is required on every mutation.** One `Idempotency-Key` covers a whole
  initialize + finalize pair; reuse it across the two rather than minting a second.
- **A refund unwinds the split per party's share.** You do not reverse it by hand.
- **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.

## 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)