Payout Gateway/Docs
Home
GuidesAPI Reference

List your payees

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

List this client's payees, newest first, with cursor pagination. Filter by kyc status and/or payable.

Required scope: payees:read.

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

Query Parameters

limit?integer

Page size, 1–100. Defaults to 100; values above 100 are clamped.

Range1 <= value <= 100
Default100
cursor?string

Opaque pagination cursor — pass back the nextCursor from the previous page to fetch the next. It is the ISO-8601 createdAt of the last row returned. The boundary is exclusive (rows strictly older than this createdAt). createdAt is not guaranteed unique; rows sharing the boundary createdAt may be skipped. Treat the cursor as opaque and stop when nextCursor is null.

Formatdate-time
kyc?string

Filter by KYC status.

Value in

  • "none"
  • "pending"
  • "verified"
  • "rejected"
payable?boolean

Filter by payability. Only the literal values true and false are recognized; any other value is silently ignored (no filter applied).

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!,});let cursor: string | undefined;do {  const page = await client.listPayees({ payable: true, limit: 100, cursor });  for (const payee of page.data) console.log(payee.externalId, payee.kycStatus);  cursor = page.nextCursor ?? undefined;} while (cursor);
{  "data": [    {      "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    }  ],  "nextCursor": "2019-08-24T14:15:22Z"}

API Reference

Every endpoint and webhook in the v1 contract, grouped by resource.

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