Skip to content

The complete open source platform to run your entire marketplace. Storefront, vendor panel, admin console, and integrations in one enterprise-grade platform you own.

7.3 KB
Raw Blame
---
title: "Payout module service"
sidebarTitle: "Service"
description: "Resolve the Payout module service, and use its generated data methods and its provider-backed methods."
---

`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, events, or a rollback.

## Resolve the service

The service is registered under `MercurModules.PAYOUT`, whose value is `"payout"`:

```ts
import { IPayoutModuleService, MercurModules } from "@mercurjs/types"

const payoutService = container.resolve<IPayoutModuleService>(MercurModules.PAYOUT)

const [payouts, count] = await payoutService.listAndCountPayouts(
  { status: "on_hold" },
  { take: 20, order: { created_at: "DESC" } }
)
```

## Generated methods

The service extends `MedusaService({ Onboarding, Payout, PayoutAccount, PayoutReversal })` and implements `IPayoutModuleService` from `@mercurjs/types`, so each model gets Medusa’s standard methods. Resolve it with that interface: `container.resolve<IPayoutModuleService>(MercurModules.PAYOUT)`.

| Model | Methods |
| --- | --- |
| `PayoutAccount` | `retrievePayoutAccount`, `listPayoutAccounts`, `listAndCountPayoutAccounts`, `createPayoutAccounts`, `updatePayoutAccounts`, `deletePayoutAccounts`, `softDeletePayoutAccounts`, `restorePayoutAccounts` |
| `Onboarding` | `retrieveOnboarding`, `listOnboardings`, `listAndCountOnboardings`, `createOnboardings`, `updateOnboardings`, `deleteOnboardings`, `softDeleteOnboardings`, `restoreOnboardings` |
| `Payout` | `retrievePayout`, `listPayouts`, `listAndCountPayouts`, `createPayouts`, `updatePayouts`, `deletePayouts`, `softDeletePayouts`, `restorePayouts` |
| `PayoutReversal` | `retrievePayoutReversal`, `listPayoutReversals`, `listAndCountPayoutReversals`, `createPayoutReversals`, `updatePayoutReversals`, `deletePayoutReversals`, `softDeletePayoutReversals`, `restorePayoutReversals` |

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’s `createAccount` with `data.account_id` and `metadata.account_id` set to the new id, then stores `external_id`, the flags, the derived `status` and `kyc_status`, and the provider’s `data`. Deletes the row if the provider throws. `input` takes optional `data`, `context`, and `seller` (used when `onboarding.prefill` is on).

### syncPayoutAccount

```ts
syncPayoutAccount(accountId: string): Promise<PayoutAccountDTO>
```

Re-reads the account with the provider’s `retrieveAccount` and stores the same fields as `createPayoutAccount`, plus `last_synced_at`. Clears `onboarding_token` once details are submitted. The account `status` and `kyc_status` are derived here from the provider’s flags, requirements and `disabled_reason`.

### deletePayoutAccount

```ts
deletePayoutAccount(accountId: string): Promise<void>
```

Deletes the account at the provider with its optional `deleteAccount`, then the row. `createPayoutAccountWorkflow` calls it when it rolls back, so the provider isn’t left with an account no seller is linked to. A provider without `deleteAccount` keeps its account.

### createOnboarding

```ts
createOnboarding(input: CreateOnboardingDTO): Promise<OnboardingDTO>
```

Publishes the link the seller follows next and stores it on the account’s onboarding record:

- Before the seller submits their details, it calls the provider’s `createOnboarding` with `refresh_url` and `return_url` from `input.data` or the module’s `onboarding` options, and stores the link with `kind: "onboarding"`. The refresh URL carries the account’s `onboarding_token`. A new token is issued when the account has none, when the current one is older than `onboarding.tokenTtlSeconds`, or when `input.rotate_token` is set, and `onboarding_token_issued_at` records when.
- Once `details_submitted` is set, it asks the provider’s `createLoginLink` for a dashboard link and stores it with `kind: "login"`. A provider without `createLoginLink` gets a new onboarding link instead.

`input` takes `account_id` and optional `data`, `context` and `rotate_token`.

### processPayout

```ts
processPayout(payoutId: string): Promise<PayoutDTO>
```

Sends a `pending` or `failed` payout with the provider’s `createPayout`, passing the order id as `group`, the payment in `data.source_payment`, and `{ payout_id, order_id }` as metadata. Like Medusa’s `capturePayment`, it locks the row and marks it `processing` in a transaction, then calls the provider outside it, so the lock is never held across the provider call. Stores the provider’s `status` and id. A provider error doesn’t throw: the row gets `status_reason: "provider_error"`, the message in `data.status_detail`, and the status `failed`, or `aborted` when the error is a `PayoutProviderError` with code `final`. Any other status is returned unchanged.

### processPayoutReversal

```ts
processPayoutReversal(reversalId: string): Promise<PayoutReversalDTO>
```

Sends a `pending` or `failed` reversal with the provider’s `reversePayout`, against the provider id kept in the payout’s `data.provider.id`. Locks and records errors the same way as `processPayout`.

### getWebhookActionAndData

```ts
getWebhookActionAndData(
  input: PayoutWebhookActionInput
): Promise<PayoutWebhookResult>
```

Passes `{ data, rawData, headers }` to the provider and returns its action and the provider’s object id. It doesn’t change any record.

### getOptions

```ts
getOptions(): ResolvedPayoutModuleOptions
```

Returns the resolved module options, `onboarding.returnUrl`, `onboarding.refreshBaseUrl`, `onboarding.prefill`, `onboarding.defaultCountry`, and `onboarding.tokenTtlSeconds` (24 hours by default), with defaults applied. Scheduling options belong to the integration that runs the payouts, such as the Stripe connector plugin.

## Idempotency keys

Each provider-backed method sets `context.idempotency_key` before it calls the provider:

| Method | Key |
| --- | --- |
| `createPayoutAccount` | The new `pacc` id, unless you pass one |
| `createOnboarding` | The `account_id`, unless you pass one |
| `processPayout` | The `pout` id, then `<id>:<attempt>` after a refusal |
| `processPayoutReversal` | The reversal id, then `<id>:<attempt>` after a refusal |

The key in use is stored in the row’s `data.idempotency_key` and the attempt count in `data.attempts`. What happens to the key depends on the error the provider throws:

| Error | Row | Next attempt |
| --- | --- | --- |
| `PayoutProviderError` with code `refused` | `failed` | A fresh key: the provider refused the request and created nothing, and it would return the cached refusal for the old key |
| `PayoutProviderError` with code `final` | `aborted` | None |
| Any other error (timeout, network, provider 5xx), or code `unknown` | `failed` | The same key, so if the provider did make the payout, the retry gets that payout back instead of a second one |

A `payout.failed` webhook also clears the key, because the provider failed the payout it made under it. Stripe Connect forwards the key to Stripe on account, transfer, and reversal creation.