Email the payee a hosted portal (wallet) link
Send the payee a signed, single-use link that lands them already
authenticated in their gateway portal wallet (/portal) — no separate
gateway login. The link is delivered only to the payee's own email address
and is never returned in the response: it is a bearer credential that
establishes a browser session and satisfies the withdraw
re-authentication step-up for roughly one hour, and a portal session spans
every client that shares the payee's email. Returning it would let a client
obtain a working session for an address it merely asserted, so the API hands
back only a delivery acknowledgement.
The link is single-use (enforced by the gateway's auth provider) — that's also
why this is gated by its own scope rather than onboarding:write.
Required scope: portal:write.
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.
uuidRequest 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
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!,});// Emails the payee a signed, single-use sign-in link to their hosted wallet.// The link is never returned to you.await client.sendPortalLink(payeeId);{ "delivered": true}Get the payee's wallet balance GET
The payee's wallet balance — the SAME numbers the hosted payouts portal shows — so a consuming platform's own wallet (e.g. 8x-core) stays in sync with the portal by construction rather than re-deriving from its own ledger. Like `/readiness`, this is a **pull backstop**: always correct even if a balance webhook was missed. The cent amounts describe where the payee's money is in the payout lifecycle: - `withdrawableCents` — still-**owed** disbursements, not yet released into a payout. This is what the payee could withdraw right now. - `onTheWayCents` — genuinely **in transit** (submitted to a rail, awaiting settlement) — not money that still needs the payee to act. - `actionNeededCents` — money the **creator must still claim/withdraw** before it can move (e.g. a Grade payout that's been triggered but is unclaimed, or a SideShift leg-1 awaiting the payee) — NOT yet on the way. - `landedCents` — **lifetime settled** (paid). A cumulative total, not a current balance. - `heldBelowMinimumCents` — money **held only because it's under the rail's economical floor** (a `below_min_payout` hold that self-releases once the balance clears the floor). 0 when nothing is floor-held. - `minPayoutCents` — the **floor** that held money must clear to release: the floor of the rail it's held on, or (when nothing is held) the payee's currently-resolved active rail. 0 if the rail can't be resolved. - `provider` — the payee's **single resolved payout rail** (null if none). Lets a consumer tell whether `actionNeededCents` is SideShift leg-1 money already staged in the wallet (withdrawable now via leg 2) or a Grade claim / Stripe auto-send. `currency` is the ISO 4217 code for these amounts. **Required scope:** `payees:read`.
Withdraw the payee's held balance as one consolidated payout POST
Release **every still-`owed` disbursement** for this payee as a **single consolidated payout** — the money credited to their wallet and held until they choose to take it. This is the API-key counterpart to the creator pressing **Withdraw** in the hosted portal: the same release spine, the same consolidation, the same gates. Use it when you keep your own wallet UI and want an in-app "Withdraw" button to trigger the payout rather than routing the creator to the portal. **Held-by-default (per rail).** Grade holds credited money as `owed` in the wallet until an explicit withdraw (so a creator who earned across cycles takes it as ONE payout and ONE claim link). SideShift auto-releases owed into its managed wallet the moment the credit lands; the creator drains it (leg-2) later. Stripe/Tipalti auto-release only when payability flips false→true (KYC completes). Auto-release is a per-rail behavior, not a property of "custody-free rails" as a class. **No body:** a wallet withdraws what is in it; the amount, rail and consolidation are resolved server-side. Refuses with `409` if the payee is not yet payable (KYC incomplete) or a per-source min/max/frequency policy blocks it — nothing is released in that case. **Required scope:** `disbursements:write`.