@mercurjs/docs 2.3.8-canary.3 → 2.3.9-canary.1

package/content/platform/payout/overview.mdx

@@ -1,86 +1,95 @@
 ---
-title: "Payout"
+title: "Payouts"
 sidebarTitle: "Overview"
-description: "Onboard sellers to a payment provider and settle their earnings automatically."
+description: "Connect each seller to a payout provider, onboard them, and transfer their share of an order to their own account."
 ---
 
-Use Mercur to control how each seller is onboarded and settled, while the
-payment provider handles KYC.
+Use Mercur to connect each seller to a payment provider and send them their share of every order.
 
-Settlement you control is the Payout domain. Once an order is placed and
-fulfilled, it splits each seller's share out to their own connected account, so
-funds are settled per seller rather than pooled. The seller's share is the order
-total minus commission. Onboarding is provider-driven, with the payment provider
-carrying KYC, and the domain ships with a pluggable provider interface and a
-**Stripe Connect** implementation out of the box. It also runs a fully automated
-capture-and-transfer pipeline driven by scheduled jobs and provider webhooks.
+A payout is a transfer from the marketplace to one seller, for one order. The Payout module holds 3 records: the seller’s payout account, its onboarding state, and the payouts made to it. Every external call goes through a single payout provider. Stripe Connect ships as a package, and a built-in `system` provider runs when you register none.
+
+<img className="block dark:hidden" src="/images/figures/payout-overview-light.svg" alt="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." />
+<img className="hidden dark:block" src="/images/figures/payout-overview-dark.svg" alt="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." />
 
 <Note>
-  **Provider-agnostic.** The module talks to exactly one registered payout
-  provider through a single interface. Stripe Connect ships by default; any
-  other processor is a drop-in implementation of the same `IPayoutProvider`
-  contract.
+  Resolve the module service with `MercurModules.PAYOUT` from `@mercurjs/types`. Import the payout workflows from `@mercurjs/core/workflows`.
 </Note>
 
 ## Key features
 
-- **Pluggable provider interface:** one `IPayoutProvider` contract, with Stripe Connect included.
-- **Payout accounts and onboarding:** a per-seller account plus a provider onboarding record.
-- **Webhook-driven lifecycle:** account status (`PENDING` → `ACTIVE` ↔ `RESTRICTED` / `REJECTED`) tracks the provider.
-- **Automated pipeline:** a capture-check job, payment capture, a daily payout job, and transfer, with no manual steps.
-- **Commission-aware transfers:** each payout is the order total minus its commission lines.
-- **Tunable timing:** authorization window, seller-action window, capture buffer, and required fulfillment status.
+The Payout module covers a seller’s connection to the provider and each transfer made through it:
+
+- **One provider interface**: `IPayoutProvider` has 4 methods, and the module loads exactly one implementation
+- **Stripe Connect provider**: `@mercurjs/payout-stripe-connect` creates Express accounts, onboarding links, and transfers
+- **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
+- **Webhook-driven statuses**: provider webhooks move accounts and payouts between statuses through `processPayoutForWebhookWorkflow`
+- **Commission-aware amounts**: `createPayoutWorkflow` pays the order total minus the order’s commission lines
+
+## How it works
+
+A seller moves from no account to a paid order in 5 steps:
+
+1. Run `createPayoutAccountWorkflow` 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 sets the account to `active`, `restricted`, or `rejected`.
+4. Run `createPayoutWorkflow` with an order id. It computes the seller’s share and asks the provider to transfer it.
+5. Later provider webhooks update the payout’s status.
+
+<Warning>
+  Mercur doesn’t trigger step 4 for you. No scheduled job or subscriber in `@mercurjs/core` captures payments or runs `createPayoutWorkflow`. Call it from your own job, subscriber, or route. See [The payout pipeline](/platform/payout/concepts/payout-pipeline).
+</Warning>
 
 ## Get started
 
-Learn how the domain fits together.
+Learn how accounts, onboarding, and transfers fit together.
 
 <CardGroup cols={2}>
   <Card title="Accounts & onboarding" icon="id-card" href="/platform/payout/concepts/accounts-and-onboarding">
-    The payout account, its onboarding record, and provider data.
+    The payout account, its onboarding record, and the provider data they carry.
   </Card>
   <Card title="Account lifecycle" icon="arrows-rotate" href="/platform/payout/concepts/account-lifecycle">
-    Statuses and the webhook-driven transitions between them.
+    Account and payout statuses, and the webhooks that change them.
   </Card>
   <Card title="The payout pipeline" icon="arrows-turn-right" href="/platform/payout/concepts/payout-pipeline">
-    Capture check, capture, daily payout, transfer, and the provider interface.
+    What ships, what you wire yourself, and the provider interface.
   </Card>
 </CardGroup>
 
 ## Examples
 
-Build against the Payout domain in your own code.
+Build against payouts in your own server code.
 
 <CardGroup cols={2}>
   <Card title="Create a payout account" icon="plus" href="/platform/payout/guides/create-a-payout-account">
     Run `createPayoutAccountWorkflow` for a seller.
   </Card>
   <Card title="Start onboarding" icon="link" href="/platform/payout/guides/start-provider-onboarding">
-    Kick off provider onboarding with `createOnboardingWorkflow`.
+    Create a provider onboarding link with `createOnboardingWorkflow`.
   </Card>
   <Card title="Process a webhook" icon="bell" href="/platform/payout/guides/process-a-provider-webhook">
-    Turn a provider webhook into account and payout status updates.
+    Turn a provider webhook into account and payout status changes.
   </Card>
 </CardGroup>
 
 ## Resources
 
-Data models, workflows, service methods, and events for the Payout domain.
+The data models, links, workflows, service methods, and events behind payouts.
 
 <CardGroup cols={2}>
   <Card title="Data models" icon="table" href="/platform/payout/reference/data-models">
-    The `PayoutAccount`, `Onboarding`, and `Payout` entities.
+    `PayoutAccount`, `Onboarding`, and `Payout`, with every field.
   </Card>
   <Card title="Links" icon="link" href="/platform/payout/reference/links">
-    How the Payout domain links to sellers and orders.
+    How payout records link to sellers and orders.
   </Card>
   <Card title="Workflows" icon="diagram-project" href="/platform/payout/reference/workflows">
-    Account, onboarding, payout, and webhook workflows.
+    The 4 payout workflows, their steps, and their hooks.
   </Card>
   <Card title="Service" icon="gear" href="/platform/payout/reference/service">
-    Module service methods for working with records directly.
+    Generated and provider-backed methods on the module service.
   </Card>
   <Card title="Events" icon="bell" href="/platform/payout/reference/events">
-    Events that drive the payout pipeline.
+    The webhook event, the data-model events, and the reserved event names.
   </Card>
 </CardGroup>

package/content/platform/payout/reference/data-models.mdx

@@ -1,61 +1,88 @@
 ---
-title: "Data models"
+title: "Payout data models"
 sidebarTitle: "Data models"
-description: "The data models owned by the Payout domain."
+description: "Every field of PayoutAccount, Onboarding, and Payout, plus the PayoutAccountStatus and PayoutStatus enums."
 ---
 
-The Payout domain is owned by the **Payout module**. This reference lists its
-data models and their fields. For the full module overview, see the
-[Payout overview](/platform/payout/overview).
+The Payout module owns 3 data models: `PayoutAccount`, `Onboarding`, and `Payout`. They’re defined in `packages/core/src/modules/payout/models`, and the module service is registered as `MercurModules.PAYOUT`. Every model also gets Medusa’s `created_at`, `updated_at`, and `deleted_at` columns.
 
 ## PayoutAccount
 
-Table `payout_account`, id prefix `pacc`. A seller's connection to the payment
-provider. This is the record funds are transferred to.
+A seller’s connection to the payout provider. Table `payout_account`, id prefix `pacc`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `id` | text | Primary key |
-| `status` | enum | `PayoutAccountStatus`, default `pending` |
-| `data` | json | Provider-specific account data |
-| `context` | json | Nullable; per-request provider hints |
+| `id` | `text` | Primary key, such as `pacc_01JD8Q1234567` |
+| `status` | `enum` | `PayoutAccountStatus`, default `pending` |
+| `data` | `json` | Provider account data, default `{}` |
+| `context` | `json`, nullable | Provider context passed at creation |
 
-Relations: `onboarding` (one-to-one, nullable), `payouts` (one-to-many).
+Relations:
+
+- **`onboarding`**: `hasOne` `Onboarding`, nullable, mapped by `account`
+- **`payouts`**: `hasMany` `Payout`, mapped by `account`
+
+The seller is reached through the `seller_payout_account` link, not a column. See [Links](/platform/payout/reference/links).
 
 ## Onboarding
 
-Table `onboarding`, id prefix `onb`. Provider setup state for a payout account
-(for Stripe Connect, the onboarding link).
+The provider’s onboarding state for one payout account. Table `onboarding`, id prefix `onb`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `id` | text | Primary key |
-| `data` | json | Nullable; provider onboarding data |
-| `context` | json | Nullable; per-request provider hints |
-| `account_id` | text | Belongs to a `PayoutAccount` |
+| `id` | `text` | Primary key, such as `onb_01JD8Q1234567` |
+| `data` | `json`, nullable | Provider onboarding data, such as a Stripe account link |
+| `context` | `json`, nullable | Provider context from the last onboarding call |
+| `account_id` | `text` | Foreign key to `PayoutAccount` |
+
+Relations:
 
-<Note>
-  `Onboarding` is one-to-one with `PayoutAccount`. Re-running the onboarding
-  workflow updates the existing record rather than creating a second one.
-</Note>
+- **`account`**: `belongsTo` `PayoutAccount`, mapped by `onboarding`
 
 ## Payout
 
-Table `payout`, id prefix `pout`. A single transfer of a seller's earnings for
-one order.
+One transfer to a seller’s payout account. Table `payout`, id prefix `pout`.
 
-| Field | Type | Notes |
+| Field | Type | Description |
 | --- | --- | --- |
-| `id` | text | Primary key |
-| `display_id` | number | Auto-incrementing, human-readable |
-| `currency_code` | text | The payout's currency |
-| `amount` | bigNumber | Order total minus commission |
-| `data` | json | Nullable; provider transfer data |
-| `status` | enum | `PayoutStatus`, default `pending` |
-| `account_id` | text | Belongs to a `PayoutAccount` |
+| `id` | `text` | Primary key, such as `pout_01JD8Q1234567` |
+| `display_id` | `autoincrement` | Human-readable sequence number |
+| `currency_code` | `text` | Currency of the transfer |
+| `amount` | `bigNumber` | Amount sent to the seller |
+| `data` | `json`, nullable | Provider transfer data, such as a Stripe transfer |
+| `status` | `enum` | `PayoutStatus`, default `pending` |
+| `account_id` | `text` | Foreign key to `PayoutAccount` |
+
+Relations:
+
+- **`account`**: `belongsTo` `PayoutAccount`, mapped by `payouts`
+
+Indexes, both limited to rows where `deleted_at IS NULL`:
+
+- **`IDX_payout_account_id_created_at`**: on `account_id`, `created_at`
+- **`IDX_payout_status_created_at`**: on `status`, `created_at`
+
+`createPayoutWorkflow` sets `amount` to the order total minus the order’s commission lines. The model itself doesn’t store an order id. The order travels to the provider as the idempotency key, and Stripe Connect stores it as the transfer’s `transfer_group` in `data`.
 
 ## Enums
 
-**`PayoutAccountStatus`:** `pending`, `active`, `restricted`, `rejected`.
+Both enums are exported from `@mercurjs/types`.
+
+`PayoutAccountStatus`:
+
+| Member | Value |
+| --- | --- |
+| `PENDING` | `pending` |
+| `ACTIVE` | `active` |
+| `RESTRICTED` | `restricted` |
+| `REJECTED` | `rejected` |
+
+`PayoutStatus`:
 
-**`PayoutStatus`:** `pending`, `processing`, `paid`, `failed`, `canceled`.
+| Member | Value |
+| --- | --- |
+| `PENDING` | `pending` |
+| `PROCESSING` | `processing` |
+| `PAID` | `paid` |
+| `FAILED` | `failed` |
+| `CANCELED` | `canceled` |

package/content/platform/payout/reference/events.mdx

@@ -1,48 +1,74 @@
 ---
-title: "Event reference"
+title: "Payout events"
 sidebarTitle: "Events"
-description: "Events that drive the payout pipeline, for subscribers and side effects."
+description: "The payout webhook event, the data-model events the Payout module emits, and the reserved PayoutEvents names that nothing emits yet."
 ---
 
-The Payout domain is event-driven. Scheduled jobs emit events, and subscribers
-react to them to capture payments and transfer funds. Subscribe to these events
-to run your own side effects, such as notifications, ledger syncing, or follow-up
-workflows, instead of polling.
+The Payout module has one event of its own, `payout.webhook_received`, which carries provider webhooks to the shipped subscriber. Medusa also emits a created, updated, or deleted event whenever a payout record changes. Subscribe to those for side effects such as seller notifications or ledger syncs.
 
-```ts title="src/subscribers/payout-requested.ts"
+## Webhook event
+
+The `POST /hooks/payout` route emits this event with a 5000 ms delay and 3 attempts.
+
+| Event | Emitted when | Payload |
+| --- | --- | --- |
+| `payout.webhook_received` | The provider posts to `/hooks/payout` | `{ data, rawData, headers }` |
+
+`data` is the parsed body, `rawData` is the raw body, and `headers` are the request headers. The `payout-webhook` subscriber, with subscriber id `payout-webhook-handler`, handles it and runs `processPayoutForWebhookWorkflow`. The event bus serializes `rawData` as a buffer object, and the subscriber turns it back into a `Buffer` before signature checks.
+
+## Data-model events
+
+`PayoutModuleService` extends `MedusaService`, so Medusa emits an event for each row it creates, updates, or deletes. The name is the module name, the kebab-case model name, and the action. The payload is `{ id }`.
+
+| Event | Emitted when |
+| --- | --- |
+| `payout.payout-account.created` | `createPayoutAccount` inserts an account |
+| `payout.payout-account.updated` | The provider response is stored, or a webhook changes the status |
+| `payout.payout-account.deleted` | The provider call fails and the new account is removed |
+| `payout.onboarding.created` | `createOnboarding` runs for the first time on an account |
+| `payout.onboarding.updated` | `createOnboarding` runs again on the same account |
+| `payout.payout.created` | `createPayouts` inserts a `pending` payout |
+| `payout.payout.updated` | The provider response is stored, or a webhook changes the status |
+| `payout.payout.deleted` | The provider call fails and the new payout is removed |
+
+An `updated` event doesn’t say which field changed. Retrieve the record in your subscriber and read its `status`.
+
+```ts title="src/subscribers/payout-account-updated.ts"
 import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
+import { MercurModules, PayoutAccountStatus } from "@mercurjs/types"
 
-export default async function payoutRequestedHandler({
+export default async function payoutAccountUpdated({
   event,
   container,
-}: SubscriberArgs<{ order_id: string }>) {
-  const orderId = event.data.order_id
-  // ...notify the seller, write to an external ledger, etc.
+}: SubscriberArgs<{ id: string }>) {
+  const payoutService = container.resolve(MercurModules.PAYOUT)
+  const account = await payoutService.retrievePayoutAccount(event.data.id)
+
+  if (account.status === PayoutAccountStatus.RESTRICTED) {
+    const logger = container.resolve("logger")
+    logger.warn(`Payout account ${account.id} is restricted`)
+  }
 }
 
 export const config: SubscriberConfig = {
-  event: "payout.requested",
+  event: "payout.payout-account.updated",
 }
 ```
 
-## Pipeline events
+This subscriber logs a warning each time an account lands in `restricted`, which is where you’d send the seller a reminder to finish onboarding.
 
-| Event | Emitted when | Handled by |
-| --- | --- | --- |
-| `order.capture_requested` | Capture check finds an order ready to capture | The payment-capture subscriber runs `capturePaymentWorkflow` |
-| `order.authorization_expired` | Capture check finds an authorization that already expired | Order is flagged so it isn't retried |
-| `payout.requested` | Daily job finds a captured order not yet paid out | The transfer subscriber runs `createPayoutWorkflow` |
+## Reserved event names
 
-## Webhook events
+`@mercurjs/types` exports a `PayoutEvents` enum. Nothing in `@mercurjs/core` emits these events or subscribes to them, and the enum carries a TODO to move them to order events.
 
-| Event | Emitted when | Handled by |
-| --- | --- | --- |
-| `payout.webhook_received` | A provider webhook arrives | The `payout-webhook` subscriber runs `processPayoutForWebhookWorkflow` |
-
-<Note>
-  `order.capture_requested`, `order.authorization_expired`, and
-  `payout.requested` are defined on the `PayoutEvents` enum in `@mercurjs/types`.
-  The webhook subscriber resolves `payout.webhook_received` to a provider action
-  before updating status. See
-  [Account lifecycle](/platform/payout/concepts/account-lifecycle).
-</Note>
+| Member | Name |
+| --- | --- |
+| `OrderCaptureRequested` | `order.capture_requested` |
+| `OrderAuthorizationExpired` | `order.authorization_expired` |
+| `PayoutRequested` | `payout.requested` |
+
+You can emit them from your own payout trigger and subscribe to them in your project. See [The payout pipeline](/platform/payout/concepts/payout-pipeline).
+
+## Workflow hook
+
+`createPayoutWorkflow` exposes a `payoutCreated` hook with `{ order_id, payout_id }`. Use it instead of `payout.payout.created` when you need the order id, because the data-model event carries only the payout id.

package/content/platform/payout/reference/links.mdx

@@ -1,36 +1,66 @@
 ---
-title: "Links to other modules"
+title: "Payout module links"
 sidebarTitle: "Links"
-description: "How the Payout domain links to sellers and orders across the marketplace."
+description: "The 3 module links that connect payout accounts and payouts to sellers and orders."
 ---
 
-Modules in Mercur never reference each other directly. They connect through
-**module links**. The Payout module links to the Seller and Order modules. Once a
-link is defined, you retrieve related records with `query.graph` using the link
-alias.
+The Payout module never references other modules directly. 3 module links in `packages/core/src/links` connect its records to sellers and orders. Read across them with `query.graph`, and query a link’s own table by its entry name.
+
+| Link | Entry name | Cardinality | Created by |
+| --- | --- | --- | --- |
+| Seller ↔ payout account | `seller_payout_account` | One to one | `createPayoutAccountWorkflow` |
+| Payout ↔ seller | `payout_seller` | Many payouts to one seller | `createPayoutWorkflow` |
+| Order ↔ payout | `order_payout` | One order to many payouts | Nothing in core |
+
+## Seller and payout account
+
+Defined in `seller-payout-account-link.ts` between `SellerModule.linkable.seller` and `PayoutModule.linkable.payoutAccount`. Neither side is a list, so a seller has one payout account and an account belongs to one seller. `validateSellerPayoutAccountStep` enforces the one-account rule before a new link is created.
 
 ```ts
-const { data: sellers } = await query.graph({
+const { data: [seller] } = await query.graph({
   entity: "seller",
-  fields: ["id", "name", "payout_account.*", "payouts.*"],
+  fields: ["id", "name", "payout_account.id", "payout_account.status"],
+  filters: { id: "sel_01JD8Q1234567" },
 })
 ```
 
-## Sellers
+## Payout and seller
+
+Defined in `payout-seller-link.ts` between `PayoutModule.linkable.payout`, marked `isList: true`, and `SellerModule.linkable.seller`. A seller has many payouts, and each payout has one seller. `createPayoutWorkflow` creates this link right after the payout.
 
-| Linked module | Relationship |
-| --- | --- |
-| **Seller** (account) | A store has **one** payout account (`seller` ↔ `payout_account`). |
-| **Seller** (payouts) | A store has **many** payouts (`seller` ↔ `payout`, list). |
+```ts
+const { data: payouts } = await query.graph({
+  entity: "payout",
+  fields: ["id", "amount", "status", "seller.id", "seller.name"],
+  filters: { status: "paid" },
+})
+```
 
-## Orders
+The Vendor API scopes payouts by querying the link table directly, with `entity: "payout_seller"` and filters on `seller_id` and `payout_id`.
 
-| Linked module | Relationship |
-| --- | --- |
-| **Order** | An order has **many** payouts (`order` ↔ `payout`, list). |
+## Order and payout
+
+Defined in `order-payout-link.ts` between Medusa’s `OrderModule.linkable.order` and `PayoutModule.linkable.payout`, marked `isList: true`. An order can have many payouts.
+
+<Warning>
+  No workflow in core creates `order_payout` rows, so `order.payouts` is empty by default. To use this link, create it in the `payoutCreated` hook of `createPayoutWorkflow`, which receives `order_id` and `payout_id`.
+</Warning>
+
+```ts title="src/workflows/hooks/link-payout-to-order.ts"
+import { createPayoutWorkflow } from "@mercurjs/core/workflows"
+import { ContainerRegistrationKeys, Modules } from "@medusajs/framework/utils"
+import { MercurModules } from "@mercurjs/types"
+
+createPayoutWorkflow.hooks.payoutCreated(
+  async ({ order_id, payout_id }, { container }) => {
+    const link = container.resolve(ContainerRegistrationKeys.LINK)
+
+    await link.create({
+      [Modules.ORDER]: { order_id },
+      [MercurModules.PAYOUT]: { payout_id },
+    })
+  }
+)
+```
 
-<Note>
-  A payout is linked to both the order it settles and the seller it pays. The
-  account link is one-to-one, while the seller-payouts and order-payouts links
-  are lists.
-</Note>
+Once the hook runs, read an order’s payouts with `fields: ["id", "payouts.id", "payouts.status"]` on the `order` entity.

package/content/platform/payout/reference/service.mdx

@@ -1,53 +1,92 @@
 ---
-title: "Service reference"
+title: "Payout module service"
 sidebarTitle: "Service"
-description: "The Payout module service: methods for working with records directly."
+description: "Resolve the Payout module service, and use its generated data methods and its provider-backed methods."
 ---
 
-The Payout module exposes a service you can resolve from the Medusa container to
-read and write records directly, without going through a workflow. Use it inside
-custom services, subscribers, or scheduled jobs.
+`PayoutModuleService` reads and writes payout records, and it’s the only code that calls the payout provider. Resolve it from the container in subscribers, jobs, steps, and routes. Prefer the [workflows](/platform/payout/reference/workflows) when you also need links or a rollback.
+
+## Resolve the service
+
+The service is registered under `MercurModules.PAYOUT`, whose value is `"payout"`:
 
 ```ts
 import { MercurModules } from "@mercurjs/types"
 
-const payoutModuleService = container.resolve(MercurModules.PAYOUT)
+const payoutService = container.resolve(MercurModules.PAYOUT)
 
-const [payouts, count] = await payoutModuleService.listAndCountPayouts({
-  status: "paid",
-})
+const [payouts, count] = await payoutService.listAndCountPayouts(
+  { status: "paid" },
+  { take: 20, order: { created_at: "DESC" } }
+)
 ```
 
 ## Generated methods
 
-Each data model gets a standard set of auto-generated methods. For `Payout`:
+The service extends `MedusaService({ Onboarding, Payout, PayoutAccount })`, so each model gets Medusa’s standard methods:
 
-| Method | Description |
+| Model | Methods |
 | --- | --- |
-| `retrievePayout(id, config?)` | Retrieve a payout by id |
-| `listPayouts(filters?, config?)` | List payouts matching filters |
-| `listAndCountPayouts(filters?, config?)` | List payouts with a total count |
-| `updatePayouts(data)` | Update one or more payouts |
-| `deletePayouts(ids)` | Delete one or more payouts |
+| `PayoutAccount` | `retrievePayoutAccount`, `listPayoutAccounts`, `listAndCountPayoutAccounts`, `createPayoutAccounts`, `updatePayoutAccounts`, `deletePayoutAccounts`, `softDeletePayoutAccounts`, `restorePayoutAccounts` |
+| `Onboarding` | `retrieveOnboarding`, `listOnboardings`, `listAndCountOnboardings`, `createOnboardings`, `updateOnboardings`, `deleteOnboardings`, `softDeleteOnboardings`, `restoreOnboardings` |
+| `Payout` | `retrievePayout`, `listPayouts`, `listAndCountPayouts`, `updatePayouts`, `deletePayouts`, `softDeletePayouts`, `restorePayouts` |
+
+`createPayouts` isn’t in the `Payout` row because the service overrides it. The generated create and update methods write rows only. They never call the provider.
+
+## Provider-backed methods
+
+These methods call the payout provider as part of the write.
+
+### createPayoutAccount
+
+```ts
+createPayoutAccount(input: CreatePayoutAccountDTO): Promise<PayoutAccountDTO>
+```
+
+Creates the row, calls the provider with `data.account_id` set to the new id, then stores the provider’s `data` and `status`. Deletes the row if the provider throws. `input` takes optional `data` and `context`.
+
+### createOnboarding
+
+```ts
+createOnboarding(input: CreateOnboardingDTO): Promise<OnboardingDTO>
+```
+
+Calls the provider with the account’s `data` merged with `input.data`, then creates the onboarding record or updates the existing one. `input` takes `account_id` and optional `data` and `context`.
 
-The same set exists for `PayoutAccount` and `Onboarding` (e.g.
-`retrievePayoutAccount`, `listPayoutAccounts`, `updateOnboardings`).
+### createPayouts
 
-## Provider-integrated methods
+```ts
+createPayouts(input: CreatePayoutDTO): Promise<PayoutDTO>
+```
+
+Takes one payout, not an array. Throws a `NOT_ALLOWED` error when the account isn’t `active`. Otherwise it creates a `pending` row, calls the provider, and stores the provider’s `data` and `status`. Deletes the row if the provider throws. `input` takes `account_id`, `amount`, `currency_code`, and optional `data` and `context`.
+
+### getWebhookActionAndData
+
+```ts
+getWebhookActionAndData(
+  input: PayoutWebhookActionInput
+): Promise<PayoutWebhookResult>
+```
+
+Passes `{ data, rawData, headers }` to the provider and returns its action and Mercur id. It doesn’t change any record.
 
-These overrides call the configured provider as part of the operation. Prefer
-them over the raw generated creates.
+### getOptions
 
-| Method | Description |
+```ts
+getOptions(): PayoutModuleOptions
+```
+
+Returns the module options merged over `PAYOUT_MODULE_OPTION_DEFAULTS`. Core reads none of the timing options, so use them in your own payout trigger. See [The payout pipeline](/platform/payout/concepts/payout-pipeline).
+
+## Idempotency keys
+
+Each provider-backed method sets `context.idempotency_key` before it calls the provider, unless you pass one:
+
+| Method | Default key |
 | --- | --- |
-| `createPayoutAccount(input)` | Create the account and the provider's connected account |
-| `createOnboarding(input)` | Create or update onboarding via the provider |
-| `createPayouts(input)` | Initiate a transfer through the provider (account must be `ACTIVE`) |
-| `getWebhookActionAndData(input)` | Ask the provider to parse a raw webhook payload |
-| `getOptions()` | Read the module's configured options (with defaults applied) |
-
-<Warning>
-  Prefer [workflows](/platform/payout/reference/workflows) for anything that
-  touches the provider or links records. The generated `updatePayouts` /
-  `updatePayoutAccounts` write status directly and do **not** call the provider.
-</Warning>
+| `createPayoutAccount` | The new `pacc` id |
+| `createOnboarding` | The `account_id` |
+| `createPayouts` | The new `pout` id |
+
+`createPayoutWorkflow` passes the order id, which replaces the `pout` default. Stripe Connect forwards the key to Stripe on account and transfer creation.