Create a hosted onboarding link

Server URLloading...

POST

/api/v1/payees/{id}/onboarding-link

Send

Authorization

Path

Body

Get a gateway-hosted, rail-agnostic onboarding URL for a payee — like a Stripe account link. Redirect your (already-authenticated) creator to the returned url, or embed it as an iframe; they need no separate gateway login. The URL points at the gateway's own /onboard page carrying a short-lived signed token — never at Tipalti/Stripe directly — and the gateway renders the right rail behind it.

returnUrl is where the creator is sent when they finish. It must be an absolute https URL whose host is either your registered webhook domain (the host of your configured webhook URL) or the gateway's own origin; anything else is rejected at request time with 400 invalid_return_url (open-redirect protection). Localhost over http is allowed in non-production environments only. When the payee becomes payable, the gateway fires a payee.updated webhook.

The onboarding experience depends on the payee's resolved rail. Custodial rails (Stripe, Tipalti) run hosted KYC and payout-method setup up front — the payee becomes payable only after they finish, at which point payee.updated fires. Custody-free rails (Grade, SideShift) are payable-by-design at account creation; KYC and method selection happen inline at claim/withdraw time via the claim link the payout produces, so there is no method to pre-set here.

Required scope: onboarding:write.

Path Parameters

Response Body

import { PayoutClient } from '@8x-payout/sdk';const client = new PayoutClient({  baseUrl: process.env.PAYOUT_BASE_URL!,  apiKey: process.env.PAYOUT_API_KEY!,  signingSecret: process.env.PAYOUT_SIGNING_SECRET!,});const { url, provider } = await client.getOnboardingLink(  payeeId,  'https://yourapp.example.com/payouts/onboarded', // returnUrl on YOUR domain);// Redirect the creator to `url` (or pass mode: 'iframe' to embed it).

{  "url": "http://example.com",  "mode": "redirect",  "provider": "stripe"}