---
name: build-a-marketplace
description: Build a two-sided marketplace or platform that takes payments and pays sellers, using Fynex. Use when the user is building a marketplace, multi-vendor store, gig or booking platform, or any product that collects money from buyers and distributes it to sellers, and wants to know the end-to-end shape — onboarding sellers, split payments, commission, payouts and reconciliation. Start here when the request is the whole marketplace rather than one endpoint.
---

# Build a marketplace on Fynex

The whole loop, in the order you build it. Each step has its own skill with the detail.

## Vocabulary first, because it saves an afternoon

- **Seller account** — you, the platform. The party the API key belongs to.
- **Payee** — anyone you pay out to: your sellers, vendors, suppliers.
- **Wallet** — a balance, per currency. Money lands here before it leaves.

A marketplace operator is a seller account whose sellers are payees. One key covers both
the Payments API and the Billing API: [/keys](/keys).

## The loop

1. **Onboard a seller.** `POST /payments-api/v1/payees/setup` creates the payee, their
   payout method and their cashout wallet in one call. → `onboard-sellers`
2. **Take a payment, already split.** With an active split rule on the seller, put
   `orderData.payeeDistribution` on `POST /payments-api/v1/checkout` (hosted) or
   `/initialize-payment` (server-to-server). The shares must add up to the payment; your
   commission is the rule's fee on each share (or, with an `absolute`-mode rule, what its
   lines leave over). There is no separate transfer call — and no active rule means no split.
   → `split-a-payment`
3. **Pay the seller.** `POST /payments-api/v1/payouts` against
   `withdrawableBalanceMinor`, not `availableBalanceMinor`. → `handle-payouts`
4. **Know what happened.** Subscribe to webhooks rather than polling — one signed pipe,
   one signature scheme, for both APIs. Deduplicate on `eventId`.
5. **Reconcile.** → `reconcile-invoices-to-payouts`

## The three that catch people

- **Amount units.** Payments requests are major units: checkout `49.99`, payouts
  `"amount": "49.99"` as a decimal string (`amountMinor` is a deprecated fallback).
  Billing is minor units throughout. Read the field name; nothing rejects the wrong one.
- **Idempotency-Key is required on the payment operations** (checkout, initialize,
  finalize, capture, refund, refund cancel), and one key covers a whole initialize + finalize pair.
  Payouts take `idempotencyKey` in the body; payee and wallet routes do not read the header.
- **A `200` is not a successful payment.** Read `status`, then `failureCode`, which is
  enumerated in the spec with whether a retry can succeed.

## Read next

- [Getting started](/payments-api/v2/docs/getting-started.md) · [Concepts](/payments-api/v2/docs/concepts.md)
- [Test cards and sandbox](/payments-api/v2/docs/test-cards.md)
- [Agent index](/payments-api/v2/llms.txt) · [Both APIs](/)