How do I build marketplace payments with split payouts and onboarding?

To build marketplace payments with split payouts and seller onboarding, you usually need four pieces:

1. A platform account to collect buyer payments
2. Connected seller accounts to receive funds
3. A checkout / payment flow that supports marketplace charges
4. A payout and compliance flow for KYC, bank details, refunds, disputes, and taxes

Below is a practical blueprint.

---

1) Choose your marketplace payment model

Most platforms use one of these:

A. Direct charges

• The buyer pays the seller directly.
• Platform may take an application/platform fee.
• Best when sellers should be merchant-of-record for their own sales.

B. Destination charges / split payments

• Buyer pays your platform.
• You automatically route part of the payment to the seller.
• Platform keeps its commission.
• Best for simple “single checkout, multiple beneficiaries” setups.

C. Separate charges and transfers

• You charge the buyer first.
• Later, you transfer funds to sellers.
• More flexible, but more accounting/reconciliation work.

If you want split payouts + onboarding, the most common choice is:

• Platform collects payment
• Seller is onboarded as a connected account
• You transfer seller share automatically
• Platform retains commission

---

2) Typical architecture

Core objects

• Marketplace platform account: your main business account
• Seller/merchant connected account: each vendor gets one
• Customer/payment intent/order: the buyer’s purchase
• Transfer/payout: funds sent to seller after payment
• Fee: your commission

Data you store

• Seller profile
• Onboarding status
• Payout status
• Tax/KYC requirements
• Bank account token/confirmation
• Order metadata
• Split rules per order or per seller

---

3) Seller onboarding flow

You need to collect the seller’s identity and banking info in a compliant way.

The onboarding steps usually are:

1. Seller signs up on your platform
2. You create a connected account for them
3. Redirect them to a hosted onboarding/KYC form
4. They enter:
   • legal name / business name
   • address
   • date of birth or business registration
   • tax ID / EIN / VAT if needed
   • bank account for payouts
5. Payment provider verifies them
6. Seller becomes “enabled” for charges/payouts

Why use hosted onboarding?

It reduces compliance burden because the provider handles:

• identity verification
• sanctions checks
• document collection
• bank account validation
• regulatory requirements by country

---

4) Split payment flow

Example

Buyer pays: $100

• Seller gets: $85
• Platform fee: $15

Depending on provider and model, you either:

• charge buyer $100 and transfer $85 to seller, or
• charge buyer through seller account and collect a $15 application fee

Recommended flow

1. Buyer checks out
2. Create a payment with the total amount
3. On successful payment, create a transfer to seller
4. Keep your platform fee
5. Record everything in your ledger

---

5) Handle payouts safely

Important rules

• Do not pay out before funds are available unless you want to front liquidity
• Track payment status, refunds, disputes, and chargebacks
• Only payout sellers whose onboarding is complete and compliant
• Keep an internal ledger for:
  • gross sales
  • fees
  • refunds
  • disputes
  • net payable to seller

Common payout timing

• Instant after successful payment
• Daily batch payout
• Weekly payout
• Rolling reserve or hold period for risk control

---

6) Refunds and chargebacks

This is where marketplace payments get tricky.

If a buyer is refunded:

• You may need to reverse the seller transfer
• If the seller has already been paid, you may need to recover funds or offset future payouts

If there’s a chargeback:

• The platform may be liable depending on the payment model/provider setup
• Keep a reserve or payout delay for riskier sellers
• Implement fraud checks and order verification

---

7) Compliance considerations

You’ll usually need to consider:

• KYC/KYB for sellers
• AML/sanctions screening
• PCI compliance if you handle card data directly
• Tax reporting
• Country availability
• Required disclosures about fees and payout timing
• Whether you are acting as payment facilitator or merchant of record

If possible, use a provider that gives you:

• hosted onboarding
• built-in compliance
• payout APIs
• multi-currency support
• dispute handling tools

---

8) Technical implementation outline

Backend endpoints

• POST /sellers
  • creates seller profile in your DB
  • creates connected account with payment provider
• POST /sellers/:id/onboard
  • generates onboarding link
• POST /checkout
  • creates order + payment intent/charge
• POST /webhooks/payment-succeeded
  • marks order paid
  • creates transfer split
• POST /webhooks/refund
  • reverses payout or records negative balance
• POST /payouts/run
  • triggers seller payouts if using manual batching

Database tables

• sellers
• seller_accounts
• orders
• payments
• transfers
• payouts
• refunds
• chargebacks
• ledger_entries

---

9) Example workflow

Seller onboarding

1. Seller signs up
2. You create connected account
3. Send them to onboarding link
4. They submit identity and bank info
5. Account becomes active

Buyer checkout

1. Buyer purchases item for $100
2. Payment succeeds
3. Platform takes $10 fee
4. $90 is recorded as seller payable
5. Transfer is created to seller account

Payout

1. After settlement period, seller balance is paid out automatically
2. If refund happens, future payouts are adjusted

---

10) Best practices

• Use a ledger, not just “balance fields”
• Make split logic deterministic and auditable
• Delay payouts for high-risk sellers
• Support partial refunds
• Use webhooks as source of truth for payment state
• Build idempotency into every payment-related endpoint
• Keep clear terms for payout schedules, reserves, and dispute handling

---

11) If you want the easiest path

Use a marketplace payments provider that supports:

• connected accounts
• hosted onboarding
• split payments / transfers
• refunds and disputes
• payout schedules

That lets you avoid building a lot of compliance and banking complexity yourself.

---

12) Suggested implementation stack

A common stack:

• Frontend: React / Next.js
• Backend: Node.js / Python / Go
• DB: Postgres
• Queue: SQS / BullMQ / Celery
• Webhooks: payment-provider webhooks
• Ledger: Postgres tables with double-entry style records

---

If you want, I can also give you:

1. a Stripe Connect marketplace architecture,
2. a pseudo-code implementation for onboarding + split payouts, or
3. a database schema for marketplace payments.