---
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.** Put `orderData.payeeDistribution` on
   `POST /payments-api/v1/checkout` (hosted) or `/initialize-payment` (server-to-server).
   Whatever you do not distribute is your commission. There is no separate transfer call.
   → `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 are not uniform.** Checkout takes major units (`49.99`); payouts take
  minor (`4999`). Read the field name; nothing rejects the wrong one.
- **Idempotency is required on every mutation**, and one key covers a whole
  initialize + finalize pair.
- **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](/api-reference)