> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payouts

> 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.

![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.](https://mintcdn.com/mercur/KNc3NtbZ9cUlitbx/images/figures/payout-overview-light.svg?fit=max\&auto=format\&n=KNc3NtbZ9cUlitbx\&q=85\&s=cfc97b8f75ed1a7964482227adb11432)

> [!NOTE]
>
> Resolve the module service with `MercurModules.PAYOUT` from `@mercurjs/types`. Import the payout workflows from `@mercurjs/core/workflows`.

## 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](https://docs.mercurjs.com/platform/payout/concepts/payout-pipeline.md).

## Get started

Learn how accounts, onboarding, and payouts fit together.

> [card] [Accounts & onboarding](https://docs.mercurjs.com/platform/payout/concepts/accounts-and-onboarding.md)
>
> The payout account, its onboarding record, and the provider data they carry.

> [card] [Account lifecycle](https://docs.mercurjs.com/platform/payout/concepts/account-lifecycle.md)
>
> Account and payout statuses, and the webhooks that change them.

> [card] [The payout pipeline](https://docs.mercurjs.com/platform/payout/concepts/payout-pipeline.md)
>
> What core ships, what the plugin or your code schedules, and the provider interface.

## Examples

Build against payouts in your own server code.

> [card] [Create a payout account](https://docs.mercurjs.com/platform/payout/guides/create-a-payout-account.md)
>
> Run `createPayoutAccountWorkflow` for a seller.

> [card] [Start onboarding](https://docs.mercurjs.com/platform/payout/guides/start-provider-onboarding.md)
>
> Create a provider onboarding link with `createOnboardingWorkflow`.

> [card] [Process a webhook](https://docs.mercurjs.com/platform/payout/guides/process-a-provider-webhook.md)
>
> Turn a provider webhook into account and payout status changes.

## Resources

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

> [card] [Data models](https://docs.mercurjs.com/platform/payout/reference/data-models.md)
>
> `PayoutAccount`, `Onboarding`, `Payout`, and `PayoutReversal`, with every field.

> [card] [Links](https://docs.mercurjs.com/platform/payout/reference/links.md)
>
> How payout records link to sellers and orders.

> [card] [Workflows](https://docs.mercurjs.com/platform/payout/reference/workflows.md)
>
> The payout workflows, their steps, and their hooks.

> [card] [Service](https://docs.mercurjs.com/platform/payout/reference/service.md)
>
> Generated and provider-backed methods on the module service.

> [card] [Events](https://docs.mercurjs.com/platform/payout/reference/events.md)
>
> The webhook event, the failure events, and the data-model events.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.