Marketplace payments: how to design them on Stripe Connect

The four decisions that shape marketplace payments

1. Who is the merchant? The platform, or each seller? This drives whose name is on the card statement, who handles disputes, and who carries liability.
2. How does money split? One seller per payment, or a basket split across several?
3. When do sellers get paid? Immediately, on a schedule, or only after the buyer confirms delivery?
4. Who owns the seller relationship? Does the seller know Stripe exists and log into their own dashboard, or is everything white-labeled inside your product?

On Stripe Connect, decision 4 points to an account type and decisions 1 to 3 point to a charge type. Get these right and the code is straightforward. Get them wrong and you’ll be migrating live sellers later, which is painful.

Stripe Connect account types: Standard, Express, Custom

Stripe has three legacy connected account types, which its documentation now marks as deprecated for new platforms. New integrations configure accounts through the Accounts v2 API or controller properties – who pays Stripe fees, who is liable for losses, what dashboard the seller gets – but the three types still describe the common combinations well, so I use them as shorthand here.

• Standard. The seller has a full Stripe account and dashboard and a direct relationship with Stripe. Least work and least liability for the platform, but least control over the experience and payouts. Good for SaaS platforms whose customers are established businesses.
• Express. Stripe hosts onboarding and identity verification and gives sellers a lightweight dashboard. The platform controls payout timing and is responsible for disputes and negative balances. The usual starting point for a consumer-facing marketplace.
• Custom. The seller never sees Stripe. You build onboarding (or use Stripe’s embedded components), handle all seller communication, and carry the most responsibility. Only worth it when the payments experience is core to your product and you have the team to support it.

Charge types: direct, destination, or separate charges and transfers

• Direct charges. The charge is created on the seller’s connected account; the seller is the merchant, and you take an application fee. Refunds and disputes sit with the seller. Fits Standard accounts and SaaS platforms where each customer runs their own business.
• Destination charges. The charge is created on the platform with a transfer_data destination, and Stripe moves the funds to one connected account automatically, minus your application fee (or you specify the transfer amount instead). The platform is the merchant by default and pays the processing fee; on_behalf_of makes the seller the settlement merchant. Simple and clear when each payment has exactly one seller.
• Separate charges and transfers. The platform charges the buyer, then later creates one or more transfers to connected accounts, linked by a transfer_group. This is how you do split payments across several sellers, and how you delay paying a seller until something happens. Setting source_transaction on a transfer ties it to the original charge, so it can be created before those funds are available in your balance. There are restrictions on which countries the platform and sellers can be in, so check Stripe’s current cross-border rules.

My default for a two-sided marketplace is an Express-style account setup with destination charges when each order has one seller, and separate charges and transfers when orders split or payouts depend on fulfillment.

Escrow-like holds: paying sellers later

Many marketplaces want to hold the buyer’s money until delivery is confirmed. A word of caution first: “escrow” in the legal sense is a regulated activity in many jurisdictions, and holding funds for others can bring licensing obligations. Building an escrow payments platform is as much a legal question as an engineering one, so get advice for your markets. What follows are the mechanics.

There are three tools, each with limits:

• Authorize now, capture later. Place a hold on the card and capture once the seller delivers. Card authorizations expire after a short window – typically seven days for online card payments – so this only suits quick fulfillment.
• Delay the transfer. With separate charges and transfers, capture immediately and create the transfer to the seller only when the release condition is met. The money sits in your platform balance in the meantime.
• Delay the payout. Transfer to the connected account immediately but put its payouts on a manual schedule, and trigger the payout when the condition is met.

Stripe limits how long funds can be held before they must be paid out or returned, and the limits vary by country. Check the current rules before designing a long hold. At Indiemaker, a platform for buying and selling side-projects, sales go through a dedicated third-party escrow provider, not a hold on the platform’s own balance: transferring a codebase or domain takes time, and both sides need to see where their money is at every stage.

Platform fees and the ledger

With direct and destination charges, your fee is an application fee recorded on the charge. With separate charges and transfers, your fee is what you don’t transfer, less the Stripe processing fees that come out of your balance. Either way, record it explicitly in your own ledger rather than inferring it later.

A marketplace needs a double-entry ledger from the start: a payable account per seller, a platform fee revenue account, and entries for every charge, transfer, refund and payout. Without it you can’t answer “how much do we owe this seller?” with confidence. My payment reconciliation guide covers the ledger design and how to reconcile transfers and payouts.

Refunds and disputes

Refunds and disputes are where marketplace payment designs show their weak spots, because the money has often already moved to the seller.

• Direct charges: the refund or dispute comes out of the seller’s balance. You decide separately whether to refund your application fee.
• Destination charges: the platform’s balance is debited. Set reverse_transfer when refunding to pull the money back from the seller, and decide whether to refund your application fee too.
• Separate charges and transfers: the platform is debited; recover the seller’s share with a transfer reversal.
• Negative balances. If the seller has already been paid out and their balance can’t cover a reversal, the platform is usually liable on Express and Custom accounts. Holding back a reserve, or paying out after a delay, is cheaper than chasing sellers.

Write your refund and dispute policy down before building. Who pays for a refund after delivery? Who submits dispute evidence? The code follows the policy.

Seller onboarding and KYC

Sellers must be verified before they can receive payouts. Stripe collects the information through hosted onboarding links or embedded components and tells you what’s outstanding through each account’s requirements (currently due, eventually due, past due) and capabilities such as card_payments and transfers.

Listen for account.updated webhooks and reflect the seller’s status in your product. The classic failure is a seller who makes sales, never finishes verification, and then finds payouts paused – and blames you. Prompt them early, show what’s missing, and decide whether unverified sellers can list at all. The Stripe webhooks guide covers handling these events reliably, including connected-account events.

Mistakes to avoid

• Picking Custom accounts for control you don’t need, then spending months on onboarding and support work.
• Using destination charges, then discovering orders need to split across sellers.
• Paying sellers out instantly with no reserve, then absorbing every dispute.
• Calling a hold “escrow” in marketing copy without checking the legal meaning in your markets.
• No internal ledger, so seller balances live in Stripe and spreadsheets.
• Treating seller verification as a one-time step instead of an ongoing state.

Getting help

Marketplace payments touch architecture, product policy and operations at once. I’ve worked on them at Indiemaker and on payment integrations for BLU Loyalty, and the wider principles are in Payments Playbook. If you’re designing or fixing a marketplace, see my page on marketplace architecture or payment integration services.

Related

• Marketplace architecture for two-sided platforms
• Payment integration services that hold up under real customers
• Payment reconciliation for SaaS and marketplaces
• Stripe webhook handling that survives production
• Payment system architecture: the parts that matter after launch
• Fintech consulting for software that moves money