Skip to main content
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. 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.
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.
@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.

​
Get started

Learn how accounts, onboarding, and payouts fit together.

Accounts & onboarding

The payout account, its onboarding record, and the provider data they carry.

Account lifecycle

Account and payout statuses, and the webhooks that change them.

The payout pipeline

What core ships, what the plugin or your code schedules, and the provider interface.

​
Examples

Build against payouts in your own server code.

Create a payout account

Run createPayoutAccountWorkflow for a seller.

Start onboarding

Create a provider onboarding link with createOnboardingWorkflow.

Process a webhook

Turn a provider webhook into account and payout status changes.

​
Resources

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

Data models

PayoutAccount, Onboarding, Payout, and PayoutReversal, with every field.

Links

How payout records link to sellers and orders.

Workflows

The payout workflows, their steps, and their hooks.

Service

Generated and provider-backed methods on the module service.

Events

The webhook event, the failure events, and the data-model events.