Get one payee
Fetch a single payee by gateway id. A payee owned by another client is
reported as 404 (existence never leaks across tenants).
Required scope: payees:read.
Authorization
bearerAuth x8xTimestamp x8xSignature Your client API key. Authorization: Bearer <API key>. The gateway stores
only sha256(key); keys are rotatable and revocable.
In: header
Unix time (seconds) at which the request was signed. Must be within 300s of gateway time.
In: header
Hex HMAC-SHA256(signingSecret, "{timestamp}.{rawBody}") over the exact raw
request body (empty string for GET). Defeats tampering and replay.
In: header
Path Parameters
The gateway payee id.
uuidResponse Body
application/json
application/json
application/json
application/json
application/json
application/json
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 payee = await client.getPayee(payeeId);console.log(payee.payable, payee.provider);{ "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08", "source": "string", "externalId": "string", "email": "user@example.com", "country": "string", "name": "string", "kycStatus": "none", "provider": "stripe", "preferredProvider": "stripe", "payable": true}Create or update a payee POST
Onboard (or idempotently re-fetch) one of your people. Keyed on `(yourClient, externalId)` — re-sending the same `externalId` updates the existing payee rather than creating a duplicate. Send `email` so the payee can be matched in the hosted payee portal. **Required scope:** `payees:write`.
Adopt an existing provider account as a payout method POST
Attach an **already-KYC'd** provider account — a Stripe Connect `acct_…` on the gateway's own platform, or a Tipalti payee id under the gateway's payer — as this payee's payout method, bypassing hosted onboarding entirely. Use this when you're migrating a creator who is already verified on the rail directly. This is the gateway's trust boundary: the caller's payability claim is **never** believed. The gateway reads the account **live** from the rail (Stripe: `charges_enabled && payouts_enabled`; Tipalti: payable status) and sets `payable`/`onboardingStatus` from what the provider actually reports. One provider account can only ever fund **one** payee. An id already linked to a **different** payee is rejected `409` (without revealing who holds it). Re-adopting the SAME `(payee, provider, providerAccountId)` is a safe, idempotent replay. An account the rail can't confirm (nonexistent, on a foreign platform, or a failed live call) is rejected `422`. On a payable adoption the payee flips payable/verified and the same `payee.updated` webhook a normal onboarding completion fires is enqueued. **Required scope:** `payees:write`.