POST /vendor/payout-accounts/:id/onboarding.
Before you begin
You need:- A payout account for the seller, created with Create a payout account
onboarding.returnUrlandonboarding.refreshBaseUrlset on the payout module, or your ownrefresh_urlandreturn_url
Create the onboarding link
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.Refresh an expired link
Provider onboarding links expire. Call the same route again: the module finds the account’s existingOnboarding 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 Stripeacct_…id refresh_urlandreturn_url: from the module’s defaults or yourdata
account_onboarding account link.
The account becomes active by webhook
Finishing onboarding doesn’t change the account by itself. Stripe sendsaccount.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
- Process a provider webhook to follow the status update
- Account lifecycle for how Stripe updates map to statuses