> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mercurjs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Payout module

> Data models, links, service methods, and the provider interface for the Payout module.

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](/rc/learn/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

```ts theme={null}
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:

```ts theme={null}
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](/rc/references/configuration#stripe-connect-payout-provider) for its options and [Stripe Connect integration](/rc/resources/integrations/stripe-connect) for the setup guide.

## Related endpoints

* `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

## Next steps

<CardGroup cols={2}>
  <Card title="Stripe Connect integration" href="/rc/resources/integrations/stripe-connect" />

  <Card title="Configuration" href="/rc/references/configuration" />
</CardGroup>