Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

5.8 KB
Raw Blame
---
title: "Payouts"
sidebarTitle: "Overview"
description: "Connect each seller to the marketplace's payout provider, onboard them, and pay their share of each order to their own account."
---

Use Mercur to connect each seller to a payment provider and send them their share of every order.

A payout is the seller’s share of one order, sent from the marketplace to the seller’s account. The Payout module holds 4 records: the seller’s payout account, its onboarding state, the payouts made to it, and the reversals that take a refunded share back. Every external call goes through the one payout provider the marketplace registers. Stripe Connect ships as a plugin, and a built-in `system` provider runs when you register none.

<img className="block dark:hidden" src="/images/figures/payout-overview-light.svg" alt="A Payouts list in front of a Payout accounts list. Payout #12 for ACME is accented: an order total of € 47.00 minus € 4.70 commission gives a € 42.30 payout, marked Paid. Behind it, ACME's payout account is Active and GLOBEX's is Restricted." />
<img className="hidden dark:block" src="/images/figures/payout-overview-dark.svg" alt="A Payouts list in front of a Payout accounts list. Payout #12 for ACME is accented: an order total of € 47.00 minus € 4.70 commission gives a € 42.30 payout, marked Paid. Behind it, ACME's payout account is Active and GLOBEX's is Restricted." />

<Note>
  Resolve the module service with `MercurModules.PAYOUT` from `@mercurjs/types`. Import the payout workflows from `@mercurjs/core/workflows`.
</Note>

## Key features

The Payout module covers a seller’s connection to the provider and the money sent through it:

- **One provider per marketplace**: the module loads exactly one `IPayoutProvider`, shaped like Medusa’s payment providers
- **Stripe Connect plugin**: `@mercurjs/stripe-connector-plugin` creates Express accounts, onboarding and login links, and pays each payout as a Connect transfer
- **One account per store**: `createPayoutAccountWorkflow` refuses a second account for the same seller
- **Re-runnable onboarding**: `createOnboardingWorkflow` creates the onboarding record once and updates it after that
- **One payout per order**: `createOrderPayoutsWorkflow` pays the order total minus the order’s commission lines, puts orders that aren’t ready on hold, and never pays an order twice
- **Reversals like refunds**: `createPayoutReversalsWorkflow` takes each later refund’s share back, net of its commission
- **Webhook-driven statuses**: provider webhooks refresh accounts and settle payouts through `processPayoutForWebhookWorkflow`

## How it works

A seller moves from no account to a paid order in 5 steps:

1. Run `createPayoutAccountWorkflow` (or `createOrRefreshSellerPayoutAccountWorkflow`) for the seller. The provider creates a connected account.
2. Run `createOnboardingWorkflow`. The provider returns onboarding data, such as a Stripe onboarding link.
3. The provider posts webhooks to `/hooks/payout`, and the `payout-webhook` subscriber re-reads the account from the provider and sets it to `pending`, `active`, `restricted`, or `rejected`.
4. Run `createOrderPayoutsWorkflow` with order ids. It computes each seller’s share and asks the provider to pay it.
5. Run `createPayoutReversalsWorkflow` after refunds. Provider webhooks update payout statuses along the way.

<Warning>
  `@mercurjs/core` ships no scheduled jobs, so it doesn’t decide when steps 4 and 5 run. The Stripe connector plugin brings its own schedule. Without it, call the workflows from your own job, subscriber, or route. See [The payout pipeline](/platform/payout/concepts/payout-pipeline).
</Warning>

## Get started

Learn how accounts, onboarding, and payouts fit together.

<CardGroup cols={2}>
  <Card title="Accounts & onboarding" icon="id-card" href="/platform/payout/concepts/accounts-and-onboarding">
    The payout account, its onboarding record, and the provider data they carry.
  </Card>
  <Card title="Account lifecycle" icon="arrows-rotate" href="/platform/payout/concepts/account-lifecycle">
    Account and payout statuses, and the webhooks that change them.
  </Card>
  <Card title="The payout pipeline" icon="arrows-turn-right" href="/platform/payout/concepts/payout-pipeline">
    What core ships, what the plugin or your code schedules, and the provider interface.
  </Card>
</CardGroup>

## Examples

Build against payouts in your own server code.

<CardGroup cols={2}>
  <Card title="Create a payout account" icon="plus" href="/platform/payout/guides/create-a-payout-account">
    Run `createPayoutAccountWorkflow` for a seller.
  </Card>
  <Card title="Start onboarding" icon="link" href="/platform/payout/guides/start-provider-onboarding">
    Create a provider onboarding link with `createOnboardingWorkflow`.
  </Card>
  <Card title="Process a webhook" icon="bell" href="/platform/payout/guides/process-a-provider-webhook">
    Turn a provider webhook into account and payout status changes.
  </Card>
</CardGroup>

## Resources

The data models, links, workflows, service methods, and events behind payouts.

<CardGroup cols={2}>
  <Card title="Data models" icon="table" href="/platform/payout/reference/data-models">
    `PayoutAccount`, `Onboarding`, `Payout`, and `PayoutReversal`, with every field.
  </Card>
  <Card title="Links" icon="link" href="/platform/payout/reference/links">
    How payout records link to sellers and orders.
  </Card>
  <Card title="Workflows" icon="diagram-project" href="/platform/payout/reference/workflows">
    The payout workflows, their steps, and their hooks.
  </Card>
  <Card title="Service" icon="gear" href="/platform/payout/reference/service">
    Generated and provider-backed methods on the module service.
  </Card>
  <Card title="Events" icon="bell" href="/platform/payout/reference/events">
    The webhook event, the failure events, and the data-model events.
  </Card>
</CardGroup>