Payout Gateway/Docs
Home
GuidesAPI Reference

Create or update a payee

Open in ClaudeOpen in ChatGPT
POST
/api/v1/payees

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.

Authorization

bearerAuth x8xTimestamp x8xSignature
AuthorizationBearer <token>

Your client API key. Authorization: Bearer <API key>. The gateway stores only sha256(key); keys are rotatable and revocable.

In: header

x-8x-timestamp<token>

Unix time (seconds) at which the request was signed. Must be within 300s of gateway time.

In: header

x-8x-signature<token>

Hex HMAC-SHA256(signingSecret, "{timestamp}.{rawBody}") over the exact raw request body (empty string for GET). Defeats tampering and replay.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

Response 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.upsertPayee({  externalId: 'creator_8842',   // your stable id for this human (the join key)  email: 'creator@example.com',  name: 'Creator Example',  country: 'TR',                // ISO 3166-1 alpha-2});console.log(payee.id, payee.payable);
{  "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}

List your payees GET

List this client's payees, newest first, with cursor pagination. Filter by `kyc` status and/or `payable`. **Required scope:** `payees:read`.

Get one payee GET

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`.