Request a payout

Request a payout of the account's full available balance — exactly what "Pay out funds" does in the dashboard.

One request is created per side (creator, agency, affiliate, share) that has money and no open request; each is reviewed and paid on its own. There is no amount: partial payouts are not possible.

Idempotency-Key header required (1–255 printable characters, e.g. a UUID per payout you intend). Sending the same key with the same body again returns the original requests (201, with Idempotent-Replayed: true) instead of a second payout; the same key with a different body is refused with 409 idempotency_conflict. Keys are scoped to the account and your app (or, for a personal key, that key), so another app can never replay or block yours. A second call with the same key while the first is still running gets 409 payout_busy; retry it and it replays the first one's answer. Retry network errors with the same key.

Checked in this order, each with its own code: ID check (kyc_required) → payouts enabled (payouts_disabled) → not a buyer account (consumer_account) → a default payout method (no_method) → the payout wallet activated if the method is a MassPay wallet (masspay_not_activated) → the minimum (below_minimum) → no open request (request_open) → no payout being sent (in_flight). GET /payouts/summary reports the same gates up front.

The key's own account only: X-Dropfans-Account is refused, and so is a key an agency minted for an account it manages (403 agency_key_not_allowed) — an agency can never request a payout for a creator it manages.

{
  "note": "October"
}

{
  "requests": [
    {
      "id": "clxpr0001request",
      "kind": "request",
      "status": "requested",
      "amountCents": 34210,
      "currency": "USD",
      "side": "creator",
      "sides": {
        "creatorCents": 34210,
        "agencyCents": 0,
        "affiliateCents": 0,
        "shareCents": 0
      },
      "method": {
        "type": "MASSPAY",
        "label": "Payout wallet · SWE"
      },
      "note": "October",
      "failureMessage": null,
      "invoiceNumber": null,
      "requestId": null,
      "payoutId": null,
      "createdAt": "2026-10-30T09:12:00.000Z",
      "initiatedAt": null,
      "paidAt": null,
      "failedAt": null,
      "reversedAt": null,
      "reversalOfId": null
    }
  ]
}

curl -X POST "https://www.dropfans.io/api/external/payouts/requests" \
  -H "Authorization: Bearer $DROPFANS_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"note":"October"}'

import { randomUUID } from 'node:crypto';

// Keep the key with your record of this payout and reuse it on retries.
const idempotencyKey = randomUUID();
const res = await fetch('https://www.dropfans.io/api/external/payouts/requests', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
    'Idempotency-Key': idempotencyKey,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ note: 'October' }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.code}: ${data.error}`);
console.log(data.requests);

import os, uuid, requests

# Keep the key with your record of this payout and reuse it on retries.
idempotency_key = str(uuid.uuid4())
res = requests.post(
    "https://www.dropfans.io/api/external/payouts/requests",
    headers={
        "Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
    json={"note": "October"},
)
res.raise_for_status()
print(res.json()["requests"])