Payout module - MercurJS Documentation

The Payout module owns vendor payout accounts, provider onboarding, and payout records. It delegates account creation, onboarding, and payout execution to a single registered payout provider — Stripe Connect ships out of the box — and enforces that payouts only fire for active accounts. For the conceptual introduction, see Payouts.

Data models

`PayoutAccount`

Table payout_account, ID prefix pacc. One per seller (linked via the seller module).

Field	Type	Notes
`status`	enum	`PayoutAccountStatus`, default `pending`
`data`	json	Provider-owned account data
`context`	json	Nullable; creation context passed to the provider

Relations: onboarding (one-to-one), payouts (one-to-many).

`Payout`

Table payout, ID prefix pout.

Field	Type	Notes
`display_id`	autoincrement	Human-readable number
`currency_code`	text
`amount`	bigNumber
`status`	enum	`PayoutStatus`, default `pending`
`data`	json	Nullable; provider response data

`Onboarding`

Table onboarding, ID prefix onb. Holds the provider’s onboarding state for an account:

Field	Type	Notes
`data`	json	Nullable; e.g. the Stripe onboarding link
`context`	json	Nullable; e.g. return/refresh URLs

Enums

enum PayoutAccountStatus {
  PENDING = "pending",
  ACTIVE = "active",
  RESTRICTED = "restricted",
  REJECTED = "rejected",
}

enum PayoutStatus {
  PENDING = "pending",
  PROCESSING = "processing",
  PAID = "paid",
  FAILED = "failed",
  CANCELED = "canceled",
}

Links

Linked entity	Cardinality	Purpose
`Seller` ↔ `PayoutAccount`	one-to-one	A seller’s provider account
`Seller` ↔ `Payout`	one seller — many payouts	Settlement history
`Order.order` ↔ `Payout`	one order — many payouts	Traces a payout back to the order it settles

Service

PayoutModuleService extends MedusaService with auto-generated CRUD, plus:

Method	Behavior
`createPayoutAccount(input)`	Creates the local record, calls the provider with an idempotency key, stores the provider’s data and status; deletes the local record if the provider call fails
`createOnboarding(input)`	Calls the provider and upserts the onboarding record for the account
`createPayouts(input)`	Asserts the account is `active`, calls the provider, persists the payout with the provider’s data and status
`getWebhookActionAndData(input)`	Resolves an incoming provider webhook into a payout action (consumed by `POST /hooks/payout`)
`getOptions()`	Returns the merged module options

Module options

Option	Type	Default	Purpose
`providers`	array	—	Provider registrations (`resolve`, `id`, `options`)
`disabled`	boolean	`false`	Turns payout processing off
`authorizationWindowMs`	number	7 days	How long a payment authorization is trusted before capture must happen
`sellerActionWindowMs`	number	72 h	How long the seller has to act (e.g. fulfill) before escalation
`captureSafetyBufferMs`	number	24 h	Safety margin before the authorization expires
`requiredFulfillmentStatus`	string	`"fulfilled"`	Fulfillment state an order must reach before its payout is generated

Provider interface

Exactly one payout provider must be registered (under the payout_ registration prefix); the module throws at boot otherwise. A provider implements four verbs:

interface PayoutProvider {
  createPayoutAccount(input): Promise<{ data; status }>
  createOnboarding(input): Promise<{ data }>
  createPayout(input): Promise<{ data; status }>
  getWebhookActionAndData(payload): Promise<PayoutWebhookResult>
}

The Stripe Connect implementation lives in @mercurjs/payout-stripe-connect — see Configuration for its options and Stripe Connect integration for the setup guide.

GET /admin/payouts — platform-wide payout monitoring
GET /vendor/payouts, GET/POST /vendor/payout-accounts, POST /vendor/payout-accounts/:id/onboarding — seller-side account and history
POST /hooks/payout — provider webhook receiver

​Data models

​PayoutAccount

​Payout

​Onboarding

​Enums

​Links

​Service

​Module options

​Provider interface

​Related endpoints

​Next steps

Stripe Connect integration

Configuration