@mercurjs/docs 2.3.8-canary.3 → 2.3.8-canary.4

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

@@ -1,99 +1,96 @@
 ---
-title: "The payout pipeline"
+title: "How a payout reaches a seller"
 sidebarTitle: "The payout pipeline"
-description: "Capture check, payment capture, daily payout, transfer, and the provider interface."
+description: "What Mercur ships for payouts, what you trigger yourself, and how the provider interface fits in."
 ---
 
-In this document, you'll learn how an authorized payment becomes a transfer to a
-seller, and how the provider interface fits in.
+The payout pipeline is the path from a placed order to money in a seller’s account. Mercur ships the building blocks: the workflows, the webhook route and subscriber, and the provider interface. It doesn’t ship the scheduler that decides when an order is paid out. You choose that moment and call `createPayoutWorkflow` yourself.
 
-## Payout
+## What ships in `@mercurjs/core`
 
-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`.
+The core plugin gives you every piece that talks to the provider or writes payout records:
 
-```ts
-// createPayoutWorkflow computes the seller's share
-const amount = MathBN.sub(order.total, totalCommission)
-```
+- **Workflows**: `createPayoutAccountWorkflow`, `createOnboardingWorkflow`, `createPayoutWorkflow`, and `processPayoutForWebhookWorkflow`
+- **Webhook route**: `POST /hooks/payout` keeps the raw body and emits `payout.webhook_received` with a 5000 ms delay and 3 attempts
+- **Webhook subscriber**: `payout-webhook` parses the event through the provider and runs `processPayoutForWebhookWorkflow`
+- **Providers**: the built-in `system` provider, plus `@mercurjs/payout-stripe-connect` as a separate package
 
-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.
+## What you wire yourself
 
-<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>
+No scheduled job, subscriber, or route in core calls `createPayoutWorkflow`. Core also has no `jobs` directory, so nothing captures authorized payments on a timer.
 
-## 1. Capture check (every 15 min)
+`@mercurjs/types` exports a `PayoutEvents` enum with `order.capture_requested`, `order.authorization_expired`, and `payout.requested`, but nothing emits these events or subscribes to them. The enum carries a TODO to move them to order events. Treat the names as reserved, not as hooks you can listen to.
 
-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`.
+The module options also describe a capture and payout schedule. `PayoutModuleOptions` and `PAYOUT_MODULE_OPTION_DEFAULTS` define them, and `getOptions()` returns them with defaults applied, but no core code reads them:
 
-## 2. Payment capture (event-driven)
+| Option | Default | Intended meaning |
+| --- | --- | --- |
+| `disabled` | `false` | Turn off capture checks and daily payouts |
+| `authorizationWindowMs` | `604800000` (7 days) | How long an authorization stays valid |
+| `sellerActionWindowMs` | `259200000` (72 hours) | How long a seller has to act on an order |
+| `captureSafetyBufferMs` | `86400000` (24 hours) | Margin before authorization expiry |
+| `requiredFulfillmentStatus` | `"fulfilled"` | Minimum fulfillment status for a payout |
 
-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.
+<Tip>
+  Read these options in your own job with `container.resolve(MercurModules.PAYOUT).getOptions()`. That keeps your schedule configurable from `medusa-config.ts`.
+</Tip>
 
-## 3. Daily payout (1 AM UTC)
+## How createPayoutWorkflow computes the amount
 
-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`.
+`createPayoutWorkflow` takes one `order_id` and pays the seller’s share of that order. It runs 4 stages:
 
-## 4. Transfer (event-driven)
+1. Load the order with `total`, `currency_code`, `seller.payout_account`, items, and shipping methods
+2. Load every `commission_line` for those items and shipping methods, then sum their `amount`
+3. Call `createPayoutStep` with `order.total` minus the commission sum, in the order’s currency
+4. Link the payout to the seller and run the `payoutCreated` hook with `order_id` and `payout_id`
 
-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.
+For an order with a total of 47.00 and 4.70 in commission lines, the payout amount is 42.30. The workflow throws `Seller does not have a payout account` when the seller has none, and the module throws when the account isn’t `active`.
 
-<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 receives the order id as its idempotency key. With Stripe Connect, the order id also becomes the transfer’s `transfer_group`, and the seller id goes into its metadata.
 
-## The provider interface
+<Warning>
+  `createPayoutWorkflow` doesn’t check payment capture, fulfillment status, or earlier payouts for the order. Each run creates a new `Payout` row. Put those checks in the code that triggers it.
+</Warning>
 
-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.
+## Trigger payouts from your own code
 
-| 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` |
+You decide when an order is ready. This subscriber pays out when Medusa emits `order.fulfillment_created`:
 
-<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>
+```ts title="src/subscribers/payout-on-fulfillment.ts"
+import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { createPayoutWorkflow } from "@mercurjs/core/workflows"
 
-## Configuration
+export default async function payoutOnFulfillment({
+  event,
+  container,
+}: SubscriberArgs<{ order_id: string }>) {
+  await createPayoutWorkflow(container).run({
+    input: { order_id: event.data.order_id },
+  })
+}
 
-The pipeline's timing is tunable via the payout module options in
-`medusa-config.ts`:
+export const config: SubscriberConfig = {
+  event: "order.fulfillment_created",
+}
+```
 
-| Option | Default | Description |
+This fires once per fulfillment, so a partially fulfilled order would be paid more than once. Before you ship it, add a guard that skips orders already paid and orders whose payment isn’t captured. A scheduled job in `src/jobs` that scans orders works the same way.
+
+## The provider interface
+
+Every external call goes through `IPayoutProvider` from `@mercurjs/types`. The module loads exactly one provider and throws `Payout module should be initialized with exactly one provider` otherwise.
+
+| Method | Called by | Returns |
 | --- | --- | --- |
-| `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 |
+| `createPayoutAccount` | `createPayoutAccount` | Provider `id`, optional `status`, `data` |
+| `createOnboarding` | `createOnboarding` | `data`, such as a Stripe account link |
+| `createPayout` | `createPayouts` | Optional `status`, `data` |
+| `getWebhookActionAndData` | `getWebhookActionAndData` | A `PayoutWebhookResult` |
+
+When you register no provider, the module loads `system`. It returns `active` accounts and `paid` payouts without moving money, which suits local development and tests. Register Stripe Connect in `medusa-config.ts` with the [Stripe Connect integration](/resources/integrations/stripe-connect).
+
+## Related
+
+- [Account lifecycle](/platform/payout/concepts/account-lifecycle) for the statuses the webhooks set
+- [Workflows reference](/platform/payout/reference/workflows) for the `payoutCreated` hook
+- [Order commission lines](/platform/commission/concepts/order-commission-lines) for where the commission sum comes from

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

@@ -1,59 +1,83 @@
 ---
-title: "Create a payout account"
+title: "Create a payout account for a seller"
 sidebarTitle: "Create a payout account"
-description: "Create a seller's payout account with createPayoutAccountWorkflow."
+description: "Run createPayoutAccountWorkflow from your own route to connect a seller to the payout provider."
 ---
 
-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.
+Create a seller’s payout account from server code, for example in an operator route or a custom signup flow. The Vendor API already does this for sellers at `POST /vendor/payout-accounts`.
 
-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.
+## Before you begin
 
-## Run the workflow
+You need:
 
-```ts title="src/api/custom/payout-account/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createPayoutAccountWorkflow } from "@mercurjs/core/workflows"
+- A seller id, such as `sel_01JD8Q1234567`
+- A payout provider. Without one, the `system` provider creates accounts that are `active` at once
+- For Stripe Connect, `@mercurjs/payout-stripe-connect` registered on the payout module, as in the [Stripe Connect integration](/resources/integrations/stripe-connect)
 
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  const { result } = await createPayoutAccountWorkflow(req.scope).run({
-    input: {
-      seller_id: req.params.id,
-    },
-  })
+## Create the account
 
-  res.status(201).json({ payout_account: result })
-}
-```
+<Steps>
+  <Step title="Add a route that runs the workflow">
+    Create an admin route that takes the seller id from the path and the provider data from the body:
+
+    ```ts title="src/api/admin/payout-setup/[id]/route.ts"
+    import type {
+      AuthenticatedMedusaRequest,
+      MedusaResponse,
+    } from "@medusajs/framework/http"
+    import { createPayoutAccountWorkflow } from "@mercurjs/core/workflows"
+
+    type Body = { country: string }
+
+    export async function POST(
+      req: AuthenticatedMedusaRequest<Body>,
+      res: MedusaResponse
+    ) {
+      const { result } = await createPayoutAccountWorkflow(req.scope).run({
+        input: {
+          seller_id: req.params.id,
+          data: { country: req.body.country },
+        },
+      })
+
+      res.status(201).json({ payout_account: { id: result.id } })
+    }
+    ```
 
-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).
+    The workflow validates the seller has no account, creates it through the provider, and links it to the seller. The response returns only the id, because `result.data` holds the full provider object.
+  </Step>
+  <Step title="Call the route">
+    Send the seller’s country. Stripe Connect requires `country` and throws `"country" is required` without it:
 
-<Note>
-  A seller can have **only one** payout account. The workflow validates this
-  first and fails if the store already has one.
-</Note>
+    ```bash
+    curl -X POST http://localhost:9000/admin/payout-setup/sel_01JD8Q1234567 \
+      -H "Authorization: Bearer your_admin_token" \
+      -H "Content-Type: application/json" \
+      -d '{ "country": "US" }'
+    ```
 
-## Forward provider data
+    With Stripe Connect, the new account is `pending` and its `data` holds the Express account Stripe created.
+  </Step>
+</Steps>
 
-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.
+## Handle a seller that already has an account
+
+`validateSellerPayoutAccountStep` runs first and throws a `MedusaError` of type `INVALID_DATA` with the message `Seller already has a payout account`. Medusa returns it as a `400`. To reuse the existing account instead, look it up through the seller link:
 
 ```ts
-await createPayoutAccountWorkflow(req.scope).run({
-  input: {
-    seller_id: "sel_123",
-    context: { idempotency_key: "sel_123" },
-    data: { business_type: "company" },
-  },
+const { data: [seller] } = await query.graph({
+  entity: "seller",
+  fields: ["id", "payout_account.id", "payout_account.status"],
+  filters: { id: "sel_01JD8Q1234567" },
 })
 ```
 
-<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>
+## What happens when the provider call fails
+
+The module creates the `PayoutAccount` row before it calls the provider. If the provider throws, the module deletes that row and rethrows, so no orphaned account is left. The provider receives the new `pacc` id as `data.account_id` and as the default `context.idempotency_key`. Stripe Connect stores that id in the Stripe account’s `metadata.account_id`, which is how webhooks find the account later.
+
+## Next steps
+
+- [Start provider onboarding](/platform/payout/guides/start-provider-onboarding) so the seller can finish setup
+- [Account lifecycle](/platform/payout/concepts/account-lifecycle) for how the account becomes `active`
+- [Workflows reference](/platform/payout/reference/workflows) for the steps inside this workflow

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

@@ -1,38 +1,70 @@
 ---
-title: "Process a provider webhook"
+title: "Process payout provider webhooks"
 sidebarTitle: "Process a webhook"
-description: "Turn a provider webhook into account and payout status updates."
+description: "Route provider webhooks to Mercur so payout accounts and payouts pick up the provider's status changes."
 ---
 
-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.
+Connect your payout provider’s webhooks to Mercur so account and payout statuses follow the provider. You need this before any Stripe Connect account can become `active`.
 
-## The built-in path
+## Before you begin
 
-The `payout-webhook` subscriber resolves the raw payload to an action through the
-provider, then runs `processPayoutForWebhookWorkflow`:
+You need:
 
-```ts title="src/subscribers/payout-webhook.ts (shipped)"
-const processedEvent = await payoutService.getWebhookActionAndData(input)
+- A payout provider registered on the payout module, such as Stripe Connect
+- For Stripe Connect, a webhook signing secret set as the provider’s `webhookSecret` option
+- The [Stripe CLI](https://docs.stripe.com/stripe-cli) for local testing
 
-if (!processedEvent.data) {
-  return
-}
+## Receive webhooks
 
-const wfEngine = container.resolve(Modules.WORKFLOW_ENGINE)
-await wfEngine.run(processPayoutForWebhookWorkflowId, { input: processedEvent })
-```
+Mercur ships the route, the subscriber, and the workflow. You point the provider at the route and check the result.
+
+<Steps>
+  <Step title="Point the provider at /hooks/payout">
+    In production, add a Stripe webhook endpoint for events on connected accounts, with the URL `https://your_backend_url/hooks/payout` and the `account.updated` event. Locally, forward Connect events with the Stripe CLI:
+
+    ```bash
+    stripe listen --events account.updated \
+      --forward-connect-to localhost:9000/hooks/payout
+    ```
+
+    The CLI prints a signing secret. Use it as the provider’s `webhookSecret`.
+  </Step>
+  <Step title="Let the subscriber run the workflow">
+    The route emits `payout.webhook_received` with the body, raw body, and headers. It delays the event by 5000 ms and retries up to 3 times. The shipped `payout-webhook` subscriber then parses it and runs the workflow:
+
+    ```ts title="src/subscribers/payout-webhook.ts (in @mercurjs/core)"
+    const processedEvent = await payoutService.getWebhookActionAndData(input)
+
+    if (!processedEvent.data) {
+      return
+    }
+
+    const wfEngine = container.resolve(Modules.WORKFLOW_ENGINE)
+    await wfEngine.run(processPayoutForWebhookWorkflowId, {
+      input: processedEvent,
+    })
+    ```
+
+    Stripe Connect verifies the `stripe-signature` header against `webhookSecret`. A bad signature throws, and the event bus retries.
+  </Step>
+  <Step title="Check the account status">
+    Read the account to confirm the update landed:
+
+    ```ts
+    const payoutService = container.resolve(MercurModules.PAYOUT)
 
-`getWebhookActionAndData` delegates to the provider, which parses its own payload
-and returns a `PayoutWebhookResult`. The result is an `action` plus the affected
-`id`.
+    const account = await payoutService.retrievePayoutAccount(
+      "pacc_01JD8Q1234567"
+    )
+    ```
+
+    The `status` is `active`, `restricted`, or `rejected`, depending on what Stripe reported.
+  </Step>
+</Steps>
 
 ## Run the workflow directly
 
-To process an already-parsed result yourself, run the workflow with a
-`PayoutWebhookResult`:
+`processPayoutForWebhookWorkflow` takes a `PayoutWebhookResult`, so you can apply a status change without a webhook, for example in a test or a backfill script:
 
 ```ts
 import { processPayoutForWebhookWorkflow } from "@mercurjs/core/workflows"
@@ -40,35 +72,49 @@ import { processPayoutForWebhookWorkflow } from "@mercurjs/core/workflows"
 await processPayoutForWebhookWorkflow(container).run({
   input: {
     action: "payout.paid",
-    data: { id: "pout_123" },
+    data: { id: "pout_01JD8Q1234567" },
   },
 })
 ```
 
-The workflow branches on `action`, updating the account or the payout:
+The workflow runs at most one step: the one that matches `action`. An `account.*` action needs a `pacc` id, and a `payout.*` action needs a `pout` id. A missing `data.id` or the `not_supported` action changes nothing.
+
+## Map webhooks in your own provider
+
+When you write a provider, `getWebhookActionAndData` decides what each webhook means. Return the action and the Mercur id, not the provider’s id:
+
+```ts title="src/providers/acme-payouts/service.ts"
+async getWebhookActionAndData(
+  payload: PayoutWebhookActionInput
+): Promise<PayoutWebhookResult> {
+  const body = payload.data as { type: string; reference: string }
+
+  if (body.type === "transfer.settled") {
+    return { action: "payout.paid", data: { id: body.reference } }
+  }
 
-| 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 |
+  return { action: "not_supported" }
+}
+```
 
-<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>
+Verify the provider’s signature here with `payload.rawData` and `payload.headers` before you trust the body. The route keeps the raw body for this purpose.
 
-## Emit the event yourself
+## Emit the event from another route
 
-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.
+If your provider must post to a different URL, emit `payout.webhook_received` yourself with the same shape. The shipped subscriber picks it up:
 
 ```ts
 const eventBus = container.resolve(Modules.EVENT_BUS)
 
 await eventBus.emit({
   name: "payout.webhook_received",
-  data: { rawData, headers, data },
+  data: { data: req.body, rawData: req.rawBody, headers: req.headers },
 })
 ```
+
+Enable `preserveRawBody` on that route’s body parser, or signature checks will fail.
+
+## Next steps
+
+- [Account lifecycle](/platform/payout/concepts/account-lifecycle) for every action and the status it sets
+- [Events reference](/platform/payout/reference/events) for the `payout.webhook_received` payload

package/content/platform/payout/guides/start-provider-onboarding.mdx

@@ -1,50 +1,94 @@
 ---
-title: "Start provider onboarding"
+title: "Start provider onboarding for a seller"
 sidebarTitle: "Start onboarding"
-description: "Kick off provider onboarding with createOnboardingWorkflow."
+description: "Run createOnboardingWorkflow to get a provider onboarding link, such as a Stripe Connect account link, for a seller."
 ---
 
-In this guide, you'll learn how to start provider onboarding for a payout
-account from server code. Onboarding is what moves an account from `PENDING`
-toward `ACTIVE`. For Stripe Connect, it produces the hosted link the seller uses
-to submit their details.
-
-## Run the workflow
-
-`createOnboardingWorkflow` asks the provider to produce onboarding data and
-stores it as an `Onboarding` record on the account.
-
-```ts title="src/api/custom/onboarding/route.ts"
-import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
-import { createOnboardingWorkflow } from "@mercurjs/core/workflows"
-
-export async function POST(req: MedusaRequest, res: MedusaResponse) {
-  const { result } = await createOnboardingWorkflow(req.scope).run({
-    input: {
-      account_id: req.params.id,
-      context: {
-        return_url: "https://store.example.com/settings/payouts",
-      },
-    },
-  })
-
-  res.status(201).json({ onboarding: result })
-}
-```
-
-The provider-specific payload (for Stripe Connect, the onboarding URL) is stored
-in the record's `data` field for you to return to the seller.
-
-<Tip>
-  Running the workflow again on an account that already has an onboarding record
-  **updates** it in place instead of creating a second one. It is safe to call
-  whenever a seller needs a fresh link.
-</Tip>
-
-## Reaching `ACTIVE`
-
-Onboarding kicks off the flow, but the account only becomes `ACTIVE` when the
-provider confirms it via webhook. Handle that step in
-[Process a webhook](/platform/payout/guides/process-a-provider-webhook), and see
-[Account lifecycle](/platform/payout/concepts/account-lifecycle) for the full
-state model.
+Create or refresh a seller’s onboarding link from server code, so they can finish the provider’s setup. The Vendor API already does this at `POST /vendor/payout-accounts/:id/onboarding`.
+
+## Before you begin
+
+You need:
+
+- A payout account for the seller, created with [Create a payout account](/platform/payout/guides/create-a-payout-account)
+- For Stripe Connect, a `refresh_url` and a `return_url` in your vendor app
+
+## Create the onboarding link
+
+<Steps>
+  <Step title="Find the seller's payout account">
+    Onboarding runs against a `pacc` id, not a seller id. Resolve it through the `seller_payout_account` link:
+
+    ```ts title="src/api/admin/payout-setup/[id]/onboarding/helpers.ts"
+    import type { MedusaContainer } from "@medusajs/framework/types"
+    import { ContainerRegistrationKeys } from "@medusajs/framework/utils"
+
+    export async function getPayoutAccountId(
+      container: MedusaContainer,
+      sellerId: string
+    ) {
+      const query = container.resolve(ContainerRegistrationKeys.QUERY)
+      const { data: [seller] } = await query.graph({
+        entity: "seller",
+        fields: ["payout_account.id"],
+        filters: { id: sellerId },
+      })
+      return seller?.payout_account?.id as string | undefined
+    }
+    ```
+  </Step>
+  <Step title="Run the workflow from a route">
+    Pass the URLs in `data`. The module merges them with the account’s stored `data`, which carries the Stripe account `id`:
+
+    ```ts title="src/api/admin/payout-setup/[id]/onboarding/route.ts"
+    import type { MedusaRequest, MedusaResponse } from "@medusajs/framework/http"
+    import { MedusaError } from "@medusajs/framework/utils"
+    import { createOnboardingWorkflow } from "@mercurjs/core/workflows"
+    import { getPayoutAccountId } from "./helpers"
+
+    export async function POST(req: MedusaRequest, res: MedusaResponse) {
+      const accountId = await getPayoutAccountId(req.scope, req.params.id)
+      if (!accountId) {
+        throw new MedusaError(MedusaError.Types.NOT_FOUND, "No payout account")
+      }
+
+      const { result } = await createOnboardingWorkflow(req.scope).run({
+        input: {
+          account_id: accountId,
+          data: {
+            refresh_url: "https://vendor.example.com/payouts/refresh",
+            return_url: "https://vendor.example.com/payouts",
+          },
+        },
+      })
+
+      res.json({ url: result.data?.url })
+    }
+    ```
+
+    For Stripe Connect, `result.data` is the Stripe account link, and `url` is the page you redirect the seller to.
+  </Step>
+</Steps>
+
+## Refresh an expired link
+
+Stripe account links expire. Call the same route again: the module finds the account’s existing `Onboarding` record and updates its `data` instead of creating a second one. Point `refresh_url` at a page in your vendor app that calls this route, so Stripe can send the seller back for a fresh link.
+
+## Required data for Stripe Connect
+
+The Stripe Connect provider checks 3 values and throws a `MedusaError` of type `INVALID_DATA` when one is missing:
+
+- **`id`**: the Stripe account id, read from the payout account’s stored `data`
+- **`refresh_url`**: where Stripe sends the seller when the link is no longer valid
+- **`return_url`**: where Stripe sends the seller after they leave the flow
+
+Put the URLs in `data`, not `context`. The module forwards `context` to the provider, but Stripe Connect reads the URLs only from `data`.
+
+## The account becomes active by webhook
+
+Finishing onboarding doesn’t change the account by itself. Stripe sends `account.updated`, the `payout-webhook` subscriber maps it to an action, and `processPayoutForWebhookWorkflow` sets the status.
+
+## Next steps
+
+- [Process a provider webhook](/platform/payout/guides/process-a-provider-webhook) to follow the status update
+- [Account lifecycle](/platform/payout/concepts/account-lifecycle) for how Stripe updates map to statuses