Skip to main content
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
  • onboarding.returnUrl and onboarding.refreshBaseUrl set on the payout module, or your own refresh_url and return_url
1

Find the seller's payout account

Onboarding runs against a pacc id, not a seller id. Resolve it through the seller_payout_account link:
src/api/admin/payout-setup/[id]/onboarding/helpers.ts
2

Run the workflow from a route

The module fills in refresh_url and return_url from its onboarding options. Pass them in data only to override those defaults:
src/api/admin/payout-setup/[id]/onboarding/route.ts
result.data.url is the page you redirect the seller to. For Stripe Connect, the rest of result.data is the Stripe account link.
Provider onboarding 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. The default refresh_url already handles this. It points at core’s public GET /payout/onboarding/refresh?token=<onboarding_token> route, which creates a fresh link for the account that owns the token and redirects the seller to it. The module’s createOnboarding sets the onboarding_token before it publishes the first link. Each refresh rotates the token, so a refresh URL works once, and a token older than onboarding.tokenTtlSeconds (24 hours by default) is rejected with 400; the seller then gets a new link from the vendor panel.

Where Stripe Connect reads its inputs

The Stripe Connect provider uses:
  • The account: the payout account’s external_id, the Stripe acct_… id
  • refresh_url and return_url: from the module’s defaults or your data
It requests the Express capabilities first when the account doesn’t have them yet, then creates an account_onboarding account link.

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 re-reads the account from Stripe and stores its new status. Once the seller has submitted their details, the onboarding record switches to a Stripe dashboard login link.

Next steps