@mercurjs/docs 2.2.1 → 2.3.0-canary.1

package/content/platform/order-group/overview.mdx

@@ -0,0 +1,83 @@
+---
+title: "Order Group"
+sidebarTitle: "Overview"
+description: "Wrap a multi-seller cart into one shopper-facing order made of independent per-seller orders."
+---
+
+Use Order Groups to turn a single customer cart that spans multiple sellers into
+one coherent order for the shopper.
+
+A marketplace cart can contain offers from several sellers at once. On checkout,
+Mercur splits that cart into one child order per seller and wraps them in an
+**Order Group**. This is the aggregate the shopper sees as "their order". Each
+child order is then fulfilled, returned, and refunded independently, while the
+group gives you a single handle over the whole purchase.
+
+<Note>
+  An order group is the `OrderGroup` entity. It lives in the **Seller module**
+  (id prefix `og`), not a module of its own. There is no `ORDER_GROUP` module
+  key. Resolve its service through `MercurModules.SELLER`.
+</Note>
+
+## Key features
+
+- **Multi-seller checkout:** one cart with offers from many sellers becomes one group of per-seller orders.
+- **Human-readable id:** an auto-incrementing `display_id` the shopper and operator can reference.
+- **Immutable cart link:** a read-only `cart_id` back to the originating cart. Carts are frozen after checkout.
+- **Computed totals:** `seller_count` and `total` are derived at query time, never stored.
+- **Independent child orders:** fulfillment, returns, and refunds happen per seller order.
+- **Scoped visibility:** admins see every group platform-wide. Vendors see only their slice.
+
+## Get started
+
+Learn how the domain fits together.
+
+<CardGroup cols={2}>
+  <Card title="The order group" icon="layer-group" href="/platform/order-group/concepts/the-order-group">
+    The aggregate entity, its `display_id`, and the read-only cart link.
+  </Card>
+  <Card title="Order splitting" icon="scissors" href="/platform/order-group/concepts/order-splitting">
+    How a multi-seller cart is split into per-seller child orders.
+  </Card>
+  <Card title="Computed totals" icon="calculator" href="/platform/order-group/concepts/computed-totals">
+    Why `seller_count` and `total` are calculated at query time.
+  </Card>
+</CardGroup>
+
+## Examples
+
+Build against Order Groups in your own code.
+
+<CardGroup cols={2}>
+  <Card title="Retrieve an order group" icon="magnifying-glass" href="/platform/order-group/guides/retrieve-an-order-group">
+    Load a group and its aggregated child orders.
+  </Card>
+  <Card title="List order groups" icon="list" href="/platform/order-group/guides/list-order-groups">
+    Page through groups, optionally scoped to a seller.
+  </Card>
+  <Card title="Split a cart" icon="scissors" href="/platform/order-group/guides/split-a-cart">
+    Complete a multi-seller cart into a group of orders.
+  </Card>
+</CardGroup>
+
+## Resources
+
+Data models, links, workflows, service methods, and events for Order Groups.
+
+<CardGroup cols={2}>
+  <Card title="Data models" icon="table" href="/platform/order-group/reference/data-models">
+    The `OrderGroup` entity and its fields.
+  </Card>
+  <Card title="Links" icon="link" href="/platform/order-group/reference/links">
+    How order groups link to carts, orders, sellers, and offers.
+  </Card>
+  <Card title="Workflows" icon="diagram-project" href="/platform/order-group/reference/workflows">
+    Splitting, retrieving, and listing order groups.
+  </Card>
+  <Card title="Service" icon="gear" href="/platform/order-group/reference/service">
+    Seller module methods for working with groups directly.
+  </Card>
+  <Card title="Events" icon="bell" href="/platform/order-group/reference/events">
+    Events emitted as order groups are created.
+  </Card>
+</CardGroup>

package/content/platform/order-group/reference/data-models.mdx

@@ -0,0 +1,40 @@
+---
+title: "Data models"
+sidebarTitle: "Data models"
+description: "The data model owned by the Order Group domain."
+---
+
+The Order Group domain is owned by the **Seller module**. There is no separate
+order-group module. This reference lists its data model and fields. For the full
+module overview, see the [Order Group overview](/platform/order-group/overview).
+
+## OrderGroup
+
+Table `order_group`, id prefix `og`. The aggregate over the per-seller orders
+created from a single cart.
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `id` | text | Primary key (prefix `og`) |
+| `display_id` | integer | Auto-incrementing, human-readable reference |
+| `customer_id` | text | Nullable; who placed the group |
+| `cart_id` | text | The originating cart (read-only link to Cart) |
+| `seller_count` | number | **Computed**: distinct sellers with a child order |
+| `total` | bigNumber | **Computed**: sum of child order totals |
+| `created_at` / `updated_at` | dateTime | Timestamps |
+| `deleted_at` | dateTime | Nullable; soft-delete marker |
+
+Relations: `orders` (one-to-many through the `order_group_order` link table),
+`cart` (read-only, via `cart_id`).
+
+<Note>
+  `seller_count` and `total` are marked `computed()`. They hold no value on the
+  row and are aggregated from the group's child orders each time it's read. See
+  [Computed totals](/platform/order-group/concepts/computed-totals).
+</Note>
+
+<Warning>
+  The `cart_id` link is **read-only**. The cart is frozen (`completed_at` is set)
+  the moment the split runs, so it's a historical reference and can't be written
+  through the group.
+</Warning>

package/content/platform/order-group/reference/events.mdx

@@ -0,0 +1,37 @@
+---
+title: "Event reference"
+sidebarTitle: "Events"
+description: "Events emitted by the Order Group domain, for subscribers and side effects."
+---
+
+The Order Group domain emits an event when a group is created during checkout.
+Subscribe to it to run side effects such as sending an order confirmation,
+syncing external systems, or kicking off follow-up workflows, instead of polling.
+
+```ts title="src/subscribers/order-group-created.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+
+export default async function orderGroupCreatedHandler({
+  event,
+  container,
+}: SubscriberArgs<{ id: string }>) {
+  const orderGroupId = event.data.id
+  // ...send a confirmation, notify sellers, etc.
+}
+
+export const config: SubscriberConfig = {
+  event: "order_group.created",
+}
+```
+
+## Order group events
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `order_group.created` | A cart is split and its parent group is created | `{ id }` |
+
+<Note>
+  The same checkout split also emits `order.placed` for each child order created.
+  Subscribe to `order.placed` when you need to react per seller order, and to
+  `order_group.created` when you need the purchase as a whole.
+</Note>

package/content/platform/order-group/reference/links.mdx

@@ -0,0 +1,45 @@
+---
+title: "Links to other modules"
+sidebarTitle: "Links"
+description: "How the Order Group domain links to carts, orders, sellers, and offers."
+---
+
+Modules in Mercur never reference each other directly. They connect through
+**module links**. The `OrderGroup` entity (owned by the Seller module) sits at
+the center of a completed multi-seller purchase, linking the cart it came from to
+the per-seller orders it produced. Once a link is defined, you retrieve related
+records with `query.graph` using the link alias.
+
+```ts
+const { data: groups } = await query.graph({
+  entity: "order_group",
+  fields: ["id", "display_id", "cart.id", "orders.id", "orders.total"],
+})
+```
+
+## Group links
+
+| Linked module | Relationship |
+| --- | --- |
+| **Cart** | A group references the one cart it was created from (`order_group.cart_id`, **read-only**). Carts are immutable after checkout. |
+| **Order** | A group has many child orders, one per seller, through the `order_group_order` table. |
+
+## Order links
+
+The child orders produced by the split carry their own marketplace links:
+
+| Linked module | Relationship |
+| --- | --- |
+| **Seller** | Each order belongs to one seller (`order_order_seller_seller`); a seller has many orders. |
+| **Offer** | Each order line item links to the offer it was purchased from (`order_line_item` → `offer`, list on the line-item side so one offer can back many order lines). |
+
+<Note>
+  The `cart_id` link is resolved from the field on the group and can't be written
+  through the link itself. The split sets it once, at creation.
+</Note>
+
+<Tip>
+  To scope a group to a single seller, filter its child orders by
+  `orders.seller.id`. The list workflow does exactly this when you pass a
+  `sellerId`. See [List order groups](/platform/order-group/guides/list-order-groups).
+</Tip>

package/content/platform/order-group/reference/service.mdx

@@ -0,0 +1,50 @@
+---
+title: "Service reference"
+sidebarTitle: "Service"
+description: "The Seller module service and its methods for working with order group records directly."
+---
+
+Order groups are owned by the **Seller module**, so you resolve the same service
+you'd use for stores. Resolve it from the Medusa container to read and write
+`OrderGroup` records directly, without going through a workflow. Use it inside
+custom services, subscribers, or scheduled jobs.
+
+```ts
+import { MercurModules } from "@mercurjs/types"
+
+const sellerModuleService = container.resolve(MercurModules.SELLER)
+
+const [orderGroups, count] = await sellerModuleService.listAndCountOrderGroups({
+  customer_id: "cus_123",
+})
+```
+
+<Note>
+  There is no `ORDER_GROUP` module key. The `OrderGroup` model is registered on
+  the Seller module, so its service methods live on `MercurModules.SELLER`.
+</Note>
+
+## Generated methods
+
+The `OrderGroup` model gets the standard set of auto-generated methods:
+
+| Method | Description |
+| --- | --- |
+| `createOrderGroups(data)` | Create one or more order groups |
+| `retrieveOrderGroup(id, config?)` | Retrieve a group by id (with computed `seller_count` / `total`) |
+| `listOrderGroups(filters?, config?)` | List groups matching filters |
+| `listAndCountOrderGroups(filters?, config?)` | List groups with a total count |
+| `updateOrderGroups(data)` | Update one or more groups |
+| `deleteOrderGroups(ids)` | Delete one or more groups |
+
+The list, count, and retrieve methods run through the module's order-group
+repository, which aggregates each group's child orders to fill in the computed
+`seller_count` and `total`. Supported filters include `id`, `customer_id`,
+`seller_id`, `status`, `sales_channel_id`, `created_at`, `updated_at`, and `q`.
+
+<Warning>
+  Prefer [workflows](/platform/order-group/reference/workflows) for reads that
+  need aggregated child-order status, and for the checkout split. The service
+  returns the group row and its computed totals but does **not** expand child
+  orders' payment/fulfillment status, emit events, or run compensation.
+</Warning>

package/content/platform/order-group/reference/workflows.mdx

@@ -0,0 +1,39 @@
+---
+title: "Workflows"
+sidebarTitle: "Workflows"
+description: "Order group workflows, service methods, and events."
+---
+
+This reference lists the workflows, service methods, and events for the Order
+Group domain. Import workflows from `@mercurjs/core/workflows` and run them
+against the Medusa container.
+
+## Checkout workflow
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `completeCartWithSplitOrdersWorkflow` | `{ cart_id }` | Split a multi-seller cart into per-seller orders and create the parent `OrderGroup`. Returns `{ order_group_id }`. Idempotent per cart. |
+
+## Read workflows
+
+| Workflow | Input | Purpose |
+| --- | --- | --- |
+| `getOrderGroupDetailWorkflow` | `{ order_group_id, fields }` | Load one group with its child orders and derived per-order payment/fulfillment status |
+| `getOrderGroupsListWorkflow` | `{ fields, variables?, sellerId? }` | List groups with a count; `sellerId` scopes each group's child orders to a seller |
+
+<Note>
+  The read workflows always expand the group's child `orders`. Heavy relations
+  (`payment_collections`, `fulfillments`) are only kept in the response when you
+  request a matching field, and are used to derive each order's `payment_status`
+  and `fulfillment_status`.
+</Note>
+
+## Step
+
+| Step | Input | Purpose |
+| --- | --- | --- |
+| `createOrderGroupStep` | `{ customer_id?, cart_id }` | Create the `OrderGroup` record (used inside the checkout workflow, with a compensating delete) |
+
+To work with records directly instead of through a workflow, see the
+[Service reference](/platform/order-group/reference/service). To run side effects
+when a group is created, see the [Event reference](/platform/order-group/reference/events).

package/content/platform/payout/concepts/account-lifecycle.mdx

@@ -0,0 +1,75 @@
+---
+title: "Account lifecycle"
+sidebarTitle: "Account lifecycle"
+description: "Payout account statuses and the webhook-driven transitions between them."
+---
+
+In this document, you'll learn about the payout account lifecycle and how its
+status stays in sync with the provider.
+
+## Status
+
+A payout account's state is held in the `status` field of the `PayoutAccount`
+model, typed by the `PayoutAccountStatus` enum. An account moves through four
+statuses.
+
+```
+                ┌──────────┐
+                │ PENDING   │
+                └────┬─────┘
+                     │ account.activated
+                     ▼
+   ┌────────────┐   ┌────────┐
+   │ RESTRICTED  │◄─►│ ACTIVE  │
+   └────────────┘   └───┬────┘
+                        │ account.rejected
+                        ▼
+                  ┌──────────┐
+                  │ REJECTED  │
+                  └──────────┘
+```
+
+| Status | Meaning |
+| --- | --- |
+| `PENDING` | Account created, provider onboarding not yet complete. |
+| `ACTIVE` | Fully onboarded. Can receive payouts. |
+| `RESTRICTED` | Provider flagged the account, for example missing KYC. No payouts. |
+| `REJECTED` | Provider permanently disabled the account. |
+
+<Note>
+  Payouts are only created against an `ACTIVE` account. The module rejects a
+  payout for an account in any other status.
+</Note>
+
+## Webhook-driven transitions
+
+Unlike the store lifecycle, payout account transitions are **not** operator
+actions. They follow the provider. The provider sends a webhook, a subscriber
+resolves it to an action, and `processPayoutForWebhookWorkflow` updates the
+status.
+
+| Webhook action | Resulting status |
+| --- | --- |
+| `account.activated` | `ACTIVE` |
+| `account.restricted` | `RESTRICTED` |
+| `account.rejected` | `REJECTED` |
+
+```ts
+// Inside processPayoutForWebhookWorkflow
+when({ input }, ({ input }) => input.action === "account.activated")
+  .then(() =>
+    updatePayoutAccountStep({ id: input.data!.id, status: PayoutAccountStatus.ACTIVE })
+  )
+```
+
+<Tip>
+  A `RESTRICTED` account is not terminal. Once the seller resolves the
+  provider's requirements, the provider emits `account.activated` again and the
+  account returns to `ACTIVE`. `REJECTED` is the only permanent state.
+</Tip>
+
+## Payout status
+
+An individual transfer carries its own `PayoutStatus` (`PENDING` → `PROCESSING`
+→ `PAID`, or `FAILED` / `CANCELED`). Provider webhooks advance it through the
+same workflow. See [The payout pipeline](/platform/payout/concepts/payout-pipeline).

package/content/platform/payout/concepts/accounts-and-onboarding.mdx

@@ -0,0 +1,70 @@
+---
+title: "Accounts & onboarding"
+sidebarTitle: "Accounts & onboarding"
+description: "The payout account, its onboarding record, and provider-specific data."
+---
+
+In this document, you'll learn how a seller connects to a payment provider and
+where provider-specific data lives.
+
+## Payout account
+
+A payout account is the seller's connection to the payment provider. It is the
+record funds are transferred to. A payout account is represented by the
+`PayoutAccount` data model (table `payout_account`, id prefix `pacc`). It is
+created for a seller through `createPayoutAccountWorkflow`, which also links the
+account to the store.
+
+```ts
+const { result } = await createPayoutAccountWorkflow(container).run({
+  input: {
+    seller_id: "sel_123",
+    context: { /* forwarded to the provider */ },
+    data: { /* forwarded to the provider */ },
+  },
+})
+```
+
+Creating an account is a two-step operation. The module first persists the
+`PayoutAccount`. It then calls the provider to create the connected account and
+stores what the provider returns in the account's `data` field. A seller has
+**exactly one** payout account.
+
+<Note>
+  A store can only have **one** payout account. `createPayoutAccountWorkflow`
+  validates that the seller doesn't already have one before creating it.
+</Note>
+
+## Onboarding
+
+Before an account can receive funds, the seller usually has to complete
+provider-side setup, such as identity verification, bank details, or KYC. That
+state is held in the `Onboarding` data model (table `onboarding`, id prefix
+`onb`). The record is a one-to-one satellite of the payout account.
+
+```ts
+await createOnboardingWorkflow(container).run({
+  input: {
+    account_id: "pacc_123",
+    context: { return_url: "https://store.example.com/settings/payouts" },
+  },
+})
+```
+
+The workflow asks the provider to produce onboarding data (for Stripe Connect,
+an onboarding link) and stores it on the record. Running it again on an account
+that already has an onboarding record **updates** it rather than creating a
+second one.
+
+## Provider data
+
+The `data` JSON field on `PayoutAccount`, `Onboarding`, and `Payout` is where
+provider-specific values live, such as the Stripe account id, onboarding URLs, or
+transfer references. The module never interprets these fields. It forwards them
+to and from the provider.
+
+<Tip>
+  `context` carries per-request hints such as an `idempotency_key` or a
+  `return_url`, while `data` carries the durable provider payload. Both are
+  passed straight through the `IPayoutProvider` interface.
+</Tip>

package/content/platform/payout/concepts/payout-pipeline.mdx

@@ -0,0 +1,99 @@
+---
+title: "The payout pipeline"
+sidebarTitle: "The payout pipeline"
+description: "Capture check, payment capture, daily payout, transfer, and the provider interface."
+---
+
+In this document, you'll learn how an authorized payment becomes a transfer to a
+seller, and how the provider interface fits in.
+
+## Payout
+
+A payout is a single transfer of a seller's earnings for one order. It is
+represented by the `Payout` data model (table `payout`, id prefix `pout`). Its
+`amount` is the order total minus the order's commission lines, and it belongs to
+the seller's `PayoutAccount`.
+
+```ts
+// createPayoutWorkflow computes the seller's share
+const amount = MathBN.sub(order.total, totalCommission)
+```
+
+The flow is designed to run automatically. Scheduled jobs and event-driven
+subscribers move each order from authorized payment to settled transfer with no
+manual step.
+
+<Note>
+  The payout **workflows** (`createPayoutWorkflow`, `createPayoutAccountWorkflow`,
+  `createOnboardingWorkflow`, `processPayoutForWebhookWorkflow`) and the provider
+  **webhook subscriber** ship in `@mercurjs/core`. The **scheduled jobs** that
+  drive capture and daily payout are wired up in your project (under
+  `apps/api/src/jobs`), along with the `order.capture_requested` and
+  `payout.requested` events they emit. The steps below describe that intended
+  pipeline and its integration points, not jobs bundled in the core plugin.
+</Note>
+
+## 1. Capture check (every 15 min)
+
+A scheduled job scans for orders ready for capture. An order qualifies when its
+payment is `authorized`, the seller has an `ACTIVE` payout account, the order
+meets the required fulfillment status (default `fulfilled`), and no payout
+exists yet. As the capture deadline nears (authorization window minus safety
+buffer), it emits `order.capture_requested`. If the authorization already
+expired, it emits `order.authorization_expired`.
+
+## 2. Payment capture (event-driven)
+
+A subscriber listens for `order.capture_requested` and runs Medusa's
+`capturePaymentWorkflow` to capture the authorized payment. On success, the order
+is marked captured. On failure, it's flagged so it isn't retried.
+
+## 3. Daily payout (1 AM UTC)
+
+A daily job scans captured orders that haven't been paid out and emits
+`payout.requested` for each one. An order qualifies when its payment is captured,
+no payout exists yet, and the seller's account is `ACTIVE`.
+
+## 4. Transfer (event-driven)
+
+A subscriber listens for `payout.requested` and runs `createPayoutWorkflow`,
+which loads the order with its seller, payout account, and commission lines,
+computes the seller's share, calls the provider to initiate the transfer, and
+creates a `Payout` record linked to the seller.
+
+<Note>
+  The order id is used as the payout's `idempotency_key`, so a re-emitted
+  `payout.requested` event never produces a duplicate transfer.
+</Note>
+
+## The provider interface
+
+Every external operation goes through the `IPayoutProvider` contract, and the
+module registers **exactly one** provider. Stripe Connect ships out of the box.
+Any other processor implements the same four methods.
+
+| Method | Purpose |
+| --- | --- |
+| `createPayoutAccount` | Create the connected account with the provider |
+| `createOnboarding` | Produce onboarding data (e.g. a Stripe onboarding link) |
+| `createPayout` | Initiate a transfer to the seller |
+| `getWebhookActionAndData` | Parse a raw webhook into a `PayoutWebhookResult` |
+
+<Tip>
+  Provider-specific values, such as account ids, onboarding URLs, or transfer
+  references, are stored in the `data` JSON fields and never interpreted by the
+  module. The same code path works for any provider.
+</Tip>
+
+## Configuration
+
+The pipeline's timing is tunable via the payout module options in
+`medusa-config.ts`:
+
+| Option | Default | Description |
+| --- | --- | --- |
+| `disabled` | `false` | Disable both scheduled jobs |
+| `authorizationWindowMs` | 7 days | How long a payment authorization stays valid |
+| `sellerActionWindowMs` | 72 hours | Time a seller has to fulfill before the order is rejected |
+| `captureSafetyBufferMs` | 24 hours | Margin before authorization expiry to trigger capture |
+| `requiredFulfillmentStatus` | `"fulfilled"` | Minimum fulfillment status before an order is eligible |

package/content/platform/payout/guides/create-a-payout-account.mdx

@@ -0,0 +1,59 @@
+---
+title: "Create a payout account"
+sidebarTitle: "Create a payout account"
+description: "Create a seller's payout account with createPayoutAccountWorkflow."
+---
+
+In this guide, you'll learn how to create a payout account for a seller from your
+own server code. This is useful in an onboarding flow or a custom API route.
+
+Mercur exposes a `createPayoutAccountWorkflow` that persists the `PayoutAccount`,
+calls the configured provider to create the connected account, and links the
+account to the store. Run it from any place that has access to the Medusa
+container.
+
+## Run the workflow
+
+```ts title="src/api/custom/payout-account/route.ts"
+import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+import { createPayoutAccountWorkflow } from "@mercurjs/core/workflows"
+
+export async function POST(req: MedusaRequest, res: MedusaResponse) {
+  const { result } = await createPayoutAccountWorkflow(req.scope).run({
+    input: {
+      seller_id: req.params.id,
+    },
+  })
+
+  res.status(201).json({ payout_account: result })
+}
+```
+
+The new account starts in `PENDING` and can't receive payouts until the provider
+marks it `ACTIVE`. See [Start onboarding](/platform/payout/guides/start-provider-onboarding).
+
+<Note>
+  A seller can have **only one** payout account. The workflow validates this
+  first and fails if the store already has one.
+</Note>
+
+## Forward provider data
+
+The workflow accepts `data` and `context` payloads that are passed straight to
+the provider when it creates the connected account. Use them to hand the
+provider anything it needs up front.
+
+```ts
+await createPayoutAccountWorkflow(req.scope).run({
+  input: {
+    seller_id: "sel_123",
+    context: { idempotency_key: "sel_123" },
+    data: { business_type: "company" },
+  },
+})
+```
+
+<Warning>
+  If the provider call fails after the record is created, the workflow rolls the
+  account back so you don't leave a dangling `PayoutAccount` behind.
+</Warning>

package/content/platform/payout/guides/process-a-provider-webhook.mdx

@@ -0,0 +1,74 @@
+---
+title: "Process a provider webhook"
+sidebarTitle: "Process a webhook"
+description: "Turn a provider webhook into account and payout status updates."
+---
+
+In this guide, you'll learn how a provider webhook becomes account and payout
+status changes. Mercur already wires this up. A subscriber listens for
+`payout.webhook_received` and drives the update workflow. Understanding the path
+lets you emit the event yourself or extend the flow.
+
+## The built-in path
+
+The `payout-webhook` subscriber resolves the raw payload to an action through the
+provider, then runs `processPayoutForWebhookWorkflow`:
+
+```ts title="src/subscribers/payout-webhook.ts (shipped)"
+const processedEvent = await payoutService.getWebhookActionAndData(input)
+
+if (!processedEvent.data) {
+  return
+}
+
+const wfEngine = container.resolve(Modules.WORKFLOW_ENGINE)
+await wfEngine.run(processPayoutForWebhookWorkflowId, { input: processedEvent })
+```
+
+`getWebhookActionAndData` delegates to the provider, which parses its own payload
+and returns a `PayoutWebhookResult`. The result is an `action` plus the affected
+`id`.
+
+## Run the workflow directly
+
+To process an already-parsed result yourself, run the workflow with a
+`PayoutWebhookResult`:
+
+```ts
+import { processPayoutForWebhookWorkflow } from "@mercurjs/core/workflows"
+
+await processPayoutForWebhookWorkflow(container).run({
+  input: {
+    action: "payout.paid",
+    data: { id: "pout_123" },
+  },
+})
+```
+
+The workflow branches on `action`, updating the account or the payout:
+
+| Action | Effect |
+| --- | --- |
+| `account.activated` / `account.restricted` / `account.rejected` | Set account status to `ACTIVE` / `RESTRICTED` / `REJECTED` |
+| `payout.processing` / `payout.paid` / `payout.failed` / `payout.canceled` | Set payout status accordingly |
+
+<Note>
+  Actions the provider can't map return `not_supported` (or a missing `data.id`),
+  and the workflow makes no change. It is safe to hand it every event the provider
+  sends.
+</Note>
+
+## Emit the event yourself
+
+To route a custom provider integration through the same path, emit
+`payout.webhook_received` with the raw payload and let the shipped subscriber
+take over.
+
+```ts
+const eventBus = container.resolve(Modules.EVENT_BUS)
+
+await eventBus.emit({
+  name: "payout.webhook_received",
+  data: { rawData, headers, data },
+})
+```