---
title: "How do Stripe Connect payouts work for a marketplace?"
description: "Stripe Connect for marketplaces: charge types, application fees, payout schedules, KYC, and how Mercur's Stripe Connect package pays sellers on Medusa."
url: https://medusajs.com/kb/marketplaces/stripe-connect-marketplace-payouts
last_updated: 2026-10-29T06:55:50Z
topic: "marketplaces"
type: "concept"
applies_to: "Medusa v2.x"
related:
  - "https://medusajs.com/kb/marketplaces/multi-vendor-marketplace.md"
  - "https://medusajs.com/kb/marketplaces/artisan-marketplace.md"
  - "https://medusajs.com/kb/headless-checkout/stripe-vs-commerce-backend.md"
  - "https://medusajs.com/kb/headless-checkout/custom-checkout-flow.md"
sources:
  - "https://docs.stripe.com/connect/charges"
  - "https://docs.stripe.com/connect/accounts"
  - "https://docs.stripe.com/connect/accounts-v2"
  - "https://docs.stripe.com/connect/marketplace/tasks/app-fees"
  - "https://docs.stripe.com/connect/manage-payout-schedule"
  - "https://docs.stripe.com/connect/marketplace"
  - "https://docs.medusajs.com/resources/commerce-modules/payment/payment-provider/stripe"
  - "https://docs.mercurjs.com/resources/integrations/stripe-connect"
  - "https://docs.mercurjs.com/platform/payout/concepts/payout-pipeline"
  - "https://docs.mercurjs.com/platform/payout/concepts/accounts-and-onboarding"
  - "https://medusajs.com/marketplace"
---

# How do Stripe Connect payouts work for a marketplace?

> Stripe Connect pays marketplace sellers by charging the customer, transferring each seller's share to their connected account, and paying out to their bank on a schedule. For multi-seller carts, Stripe's docs point to separate charges and transfers. On Medusa, Mercur's Stripe Connect package handles seller onboarding and transfers after commission; you decide when payouts run.

## How Stripe Connect moves money in a marketplace

Stripe Connect is Stripe's product for platforms that route payments between customers and many sellers. Each seller gets a connected account, a Stripe account your platform manages on their behalf.

Money moves in three stages. A **charge** takes the customer's payment. A **transfer** moves funds from the platform's Stripe balance to a connected account's balance. A **payout** moves the connected account's balance to the seller's bank. Mercur's [Stripe Connect guide](https://docs.mercurjs.com/resources/integrations/stripe-connect) notes that transfers are instant ledger movements, while bank payouts take 1 to 3 business days depending on the country.

## Which Stripe Connect charge type fits a multi-vendor cart

Stripe's [charge types guide](https://docs.stripe.com/connect/charges) describes three options.

| Charge type | Where the charge lives | Sellers per payment | Fits |
| --- | --- | --- | --- |
| Direct charges | The connected account | One | SaaS platforms where sellers deal with their own customers |
| Destination charges | The platform, with an immediate transfer | One | Marketplaces where each order has one seller |
| Separate charges and transfers | The platform, transfers created later | Many | A single cart with goods from several sellers |

With destination charges and separate charges and transfers, Stripe debits its fees, refunds, and chargebacks from the platform balance. Separate charges and transfers is the only type that splits one payment across several sellers, and Stripe notes it needs a more complex integration.

## How the marketplace takes its commission

With destination charges, you set `application_fee_amount` on the PaymentIntent, and Stripe sends that amount back to the platform after the transfer ([application fees](https://docs.stripe.com/connect/marketplace/tasks/app-fees)). With separate charges and transfers, there is no application fee field. You keep your commission by transferring less than you charged, and Stripe recommends a ledger to track what each seller is owed.

## Connected account types and who handles KYC

Stripe's [account types page](https://docs.stripe.com/connect/accounts) now labels Standard, Express, and Custom as legacy types. Stripe recommends the [Accounts v2 API](https://docs.stripe.com/connect/accounts-v2) for new platforms, where configurations such as `merchant` and `recipient` enable receiving payments or transfers.

For existing Express accounts, Stripe handles onboarding and identity verification (KYC), and sellers get the Express Dashboard. The platform carries fraud and dispute liability for Express and Custom accounts.

## How payout timing works

Stripe pays out connected account balances on a schedule set per account. The [payout schedule](https://docs.stripe.com/connect/manage-payout-schedule) interval is `manual`, `daily`, `weekly`, or `monthly`, and a delay setting controls how long funds wait before they are available. Platforms that carry fraud and dispute liability can change the interval.

## How Mercur implements Stripe Connect payouts on Medusa

Medusa core has a [Stripe payment provider](https://docs.medusajs.com/resources/commerce-modules/payment/payment-provider/stripe) for charging customers, but no Connect payout provider. Mercur, which Medusa describes as an open core marketplace platform built by its Expert partners at Rigby, adds the `@mercurjs/payout-stripe-connect` package. It uses separate charges and transfers, so the platform is the merchant of record for VAT, disputes, and chargebacks.

```ts
{
  resolve: "@mercurjs/core/modules/payout",
  options: {
    providers: [
      {
        resolve: "@mercurjs/payout-stripe-connect",
        id: "stripe-connect",
        options: {
          apiKey: process.env.STRIPE_API_KEY,
          webhookSecret: process.env.STRIPE_PAYOUT_WEBHOOK_SECRET,
        },
      },
    ],
  },
}
```

| Step | How it works | Status |
| --- | --- | --- |
| Charge the customer once | Medusa Stripe provider with manual capture | Native |
| Split the cart per seller | Mercur order groups | Starter |
| Create and onboard sellers | Express account plus a Stripe-hosted onboarding link; the account.updated webhook sets ACTIVE, RESTRICTED, or REJECTED | Starter |
| Compute each seller's share | Order total minus commission lines | Starter |
| Transfer to the seller | Transfer linked to the charge, grouped by order id | Starter |
| Decide when to pay out | A subscriber or scheduled job that calls createPayoutWorkflow | Custom |
| Reverse transfers on refund | Your own reconciliation logic | Custom |

Mercur's [payout pipeline docs](https://docs.mercurjs.com/platform/payout/concepts/payout-pipeline) state that core doesn't ship the job that triggers payouts, and that `createPayoutWorkflow` doesn't check capture, fulfillment, or earlier payouts. Add those guards in your trigger.

## When this setup is not the right choice

- **Sellers must be the merchant of record.** Separate charges and transfers puts VAT and disputes on the platform. Direct charges need a different payout provider, which you would build.
- **You are starting a new Connect platform and want Accounts v2.** Mercur's provider creates Express accounts, a type Stripe now calls legacy. Check Stripe's current guidance before launch.
- **Long seller lead times.** Card authorizations typically expire after 7 days, per Mercur's guide, so made-to-order sellers may need a different capture strategy.

## Common questions

### What is the difference between a transfer and a payout in Stripe Connect?

A transfer moves funds from the platform's Stripe balance to a connected account's balance. A payout moves a connected account's balance to the seller's bank account on its payout schedule.

### Can I use application_fee_amount with separate charges and transfers?

No. Stripe's application fee field applies to destination and direct charges. With separate charges and transfers, the platform keeps its commission by transferring less than it charged.

### Does Medusa support Stripe Connect natively?

No. Medusa core includes a Stripe payment provider for charging customers but no Connect payout provider. Mercur adds one with the @mercurjs/payout-stripe-connect package.

### Who handles seller identity verification with Stripe Connect?

For Express connected accounts, Stripe runs onboarding and identity verification on a Stripe-hosted page. Mercur marks a seller's payout account active only after Stripe reports details submitted, charges and payouts enabled, and no outstanding requirements.

## Documentation

- [Medusa Stripe Module Provider](https://docs.medusajs.com/resources/commerce-modules/payment/payment-provider/stripe)
- [Marketplace recipe](https://docs.medusajs.com/resources/recipes/marketplace)

## Related

- [How do I build a multi-vendor marketplace with open source?](https://medusajs.com/kb/marketplaces/multi-vendor-marketplace.md)
- [How do I build an artisan marketplace with AI coding help?](https://medusajs.com/kb/marketplaces/artisan-marketplace.md)
- [Stripe vs a commerce backend: what Stripe doesn't handle](https://medusajs.com/kb/headless-checkout/stripe-vs-commerce-backend.md)
- [How to build a fully custom checkout flow](https://medusajs.com/kb/headless-checkout/custom-checkout-flow.md)