# 8x Payout Gateway

> Execution-only, custody-free, multi-rail payouts to humans. Integrate like Stripe: create a payee → hosted onboarding link → `payee.updated` webhook when payable → `POST /payouts`. The gateway owns payout identity, routing, hosted onboarding, execution, and the transaction log; it never holds balances and never tracks what you owe — you keep that ledger.

The complete, machine-readable API contract is the OpenAPI 3.1 spec. Feed it directly to your coding agent — it is the single source of truth and carries every endpoint, request/response schema, the error & held-reason catalog, the payout status lifecycle, authentication, the webhook events, rate limits, and the versioning policy in one file.

## API
- [OpenAPI 3.1 contract](https://8x-payout.com/openapi.yaml): The single source of truth. Every endpoint, schema, error/held-reason code, and webhook event. Start here.
- [API reference](https://8x-payout.com/docs/api): The same contract rendered for humans, one page per endpoint, with `@8x-payout/sdk` and cURL samples.
- Every docs page is also available as Markdown at its own URL with `.md` appended, e.g. https://8x-payout.com/docs/api/createPayout.md or https://8x-payout.com/docs/quickstart.md; add `?format=prompt` for a self-contained integration prompt (platform primer + that page).

## Guides
- [Overview & architecture](https://8x-payout.com/docs/overview): The system model in one page — the integration flow, push vs pull money models, the rails, how you learn outcomes, the status lifecycle, and test mode.
- [Quickstart](https://8x-payout.com/docs/quickstart): Zero to a first test-mode payout with the `@8x-payout/sdk`.
- [Webhooks](https://8x-payout.com/docs/webhooks): The `payout.status` and `payee.updated` events and how to verify their signatures.
- [Changelog](https://8x-payout.com/docs/changelog): Versioned, additive-only API changes.

## Key facts for integrators
- Auth: every request carries `Authorization: Bearer <apiKey>`, `x-8x-timestamp` (unix seconds, within 300s of now), and `x-8x-signature` = `HMAC-SHA256(signingSecret, "{timestamp}.{rawBody}")`. The `@8x-payout/sdk` signs for you.
- Money is always integer cents (`amountCents`); currency is ISO 4217 (USD today); timestamps are ISO 8601 UTC.
- A payout request carries `payeeId` + `amountCents`, never a destination — the gateway routes to the payee's KYC-locked method.
- Two money models: push (`POST /payouts`, `POST /payouts/batch`) pays now; pull (`POST /disbursements`) credits an owed wallet the creator withdraws later.
- Learn outcomes from `payout.status` / `payee.updated` webhooks (verify the signature); poll `GET /api/v1/payouts/{id}` as a backstop. Email is creator-facing, not your integration signal.
- `paid` means funds were released to the rail, not that they landed in a bank — key off `settledAt` for confirmed arrival.
- A `held` payout is recoverable: read `statusReason`, clear the blocker, call `POST /payouts/{id}/release`. A `failed` payout with `failureKind: transient` is safe to `retry`.
- Test mode is a property of your client (same base URL) and routes everything through the mock provider — run the whole contract with no real money.