Skip to main content
The integration has three layers. Stripe holds the money and the connected accounts. Mercur core’s payout module records what each seller is owed per order. The Stripe connector plugin decides when each step runs and adds everything that is Stripe-specific.

​
What runs where

Core ships no schedule. Its workflows, createOrderPayoutsWorkflow and createPayoutReversalsWorkflow, decide and send whatever they’re called with. The plugin’s jobs and subscribers call them, and add the backlog, checkpoints and run records around them.

​
Stripe objects

Every call that moves money carries an idempotency key built from the Mercur record id and its attempt number, so a job that resends the same attempt never moves money twice. Transfers use source_transaction, so a payout can be sent as soon as the charge is captured, even while the funds are still pending on the platform balance.

​
Anatomy of an order

A customer buys from two sellers in one cart, and pays once.
  1. Checkout. The payment provider creates one PaymentIntent for the cart with manual capture. The card is authorized, not charged. Mercur splits the cart into an order group with one order per seller and writes commission lines. The plugin opens a capture for the order group.
  2. Orders are decided. Each seller fulfills or cancels their order. Every fulfillment and cancellation refreshes the capture.
  3. Capture. Once every order is decided, the capture job captures the authorized amount minus canceled orders. If every order was canceled, it cancels the authorization instead. Medusa then gives each seller order its own captured payment on the same charge.
  4. Payout. The capture runs the payout pass. For each fulfilled, captured order, core writes a payout of the order total minus commission, net of refunds that already landed, and the provider sends it as a Transfer.
  5. Refund. A refund on a paid order writes a payout_reversal of the seller’s share, net of its commission share, and the provider reverses that much of the Transfer.
  6. Settlement. Every night the settlement job nets the seller’s paid payouts, reversals and adjustments since the previous settlement, per currency, and sends the total to the seller’s bank as a Stripe Payout.
  7. Webhooks. account.updated keeps the payout account in step with Stripe. Bank payout.* events move the settlement to Paid out or Failed.

​
When each step runs

Every step runs from a scheduled job, so nothing is lost if an event is missed. Most also run right away from a subscriber, so sellers don’t wait for the next tick. The scheduled jobs and their default times are listed in the reference.

​
Job runs and checkpoints

Every run of every job, whether scheduled, started with Run now or started by a subscriber, writes a job run with its trigger, its status and counts of what it did. A job that is already running isn’t started twice. Jobs that scan for new work keep a checkpoint, the timestamp they last read up to, so each run reads only what changed. A job that fails leaves its checkpoint where it was and reads the same window again next time. Jobs that act on many sellers or orders run one workflow per item. A seller whose account Stripe rejects is recorded as failed, and the rest go through.

​
Settlement modes

settlements.mode decides who sends the bank payout: Use plugin when you want one deposit per period that matches the seller’s statement to the cent. Use provider when you prefer Stripe’s daily or weekly schedule and only need the netting for reporting.