> ## Documentation Index > Fetch the complete documentation index at: https://www.dropfans.io/developers/llms.txt > Use this file to discover all available pages before exploring further. # GET /api/external/payouts/{id} — One payout or payout request > One row of the history by id — a payout, a manual payout or a payout request — in any status, including failed attempts, fulfilled requests and reversal rows. - Source: https://www.dropfans.io/developers/reference/get-payout - Section: API reference - OpenAPI: https://www.dropfans.io/developers/openapi.json One row of the history by id — a payout, a manual payout or a payout request — in any status, including failed attempts, fulfilled requests and reversal rows. The same shape as the [payout.* webhooks](https://www.dropfans.io/developers/webhooks/overview.md) (which add `accountId`). ## Authentication `Authorization: Bearer dpfn_...` — an API key generated in the dashboard (Vault → API Connect). By default the key acts for the one account it belongs to. Missing or invalid keys return 401 `{"error":"Unauthorized","code":"unauthorized"}`. Optional `X-Dropfans-Account: ` — with a verified agency's own key, act for a creator or AI persona the agency manages (ids from GET /api/external/agency/creators); the agency needs `canViewStats` on that account. The response echoes the account acted on in the same header. ## Path parameters | Field | Type | Required | Description | |---|---|---|---| | `id` | string | yes | Row id from the list, a webhook or POST /payouts/requests. | ## Responses ### 200 The row. Money in cents. | Field | Type | Required | Description | |---|---|---|---| | `id` | string | yes | Id of the row. Unique across the three kinds — use it with GET /api/external/payouts/{id}. | | `kind` | `payout` \\| `manual` \\| `request` | yes | `payout`: sent by Dropfans (Paxum, MassPay wallet load, or settled by an admin). `manual`: paid outside the platform and recorded by an admin. `request`: a payout request the account made that has not been fulfilled into a payout yet. | | `status` | `requested` \\| `approved` \\| `pending` \\| `processing` \\| `paid` \\| `failed` \\| `cancelled` \\| `rejected` | yes | Requests: `requested` → `approved` → (`processing` for Paxum, from the moment they are made) → `paid`, or `rejected` / `cancelled`. Payouts: `pending` (in a batch, not sent yet) → `processing` (sent) → `paid` or `failed`; `cancelled` when an attempt was dropped. Manual payouts are always `paid`. | | `amountCents` | integer | yes | Integer **cents**. What is paid out (negative only on a reversal row). | | `currency` | `USD` | yes | Always "USD". | | `side` | string | yes | Which balance it draws from: `creator` (own sales), `agency` (income from managed creators / AI personas), `affiliate` (referral commission), `share` (partner shares of other accounts’ sales), or `combined` (several sides in one transfer — see `sides`). | | `sides` | object | yes | The amount split by side, integer cents. Adds up to `amountCents`. | | `sides.creatorCents` | integer | yes | Creator side, cents. | | `sides.agencyCents` | integer | yes | Agency side, cents. | | `sides.affiliateCents` | integer | yes | Referral commission, cents. | | `sides.shareCents` | integer | yes | Partner shares, cents. | | `method` | object \\| null | | The destination frozen when the payout or request was made, masked. Null for manual payouts. | | `method.type` | `PAXUM_P2P` \\| `MASSPAY` \\| `BANK_SWIFT` | yes | Provider method type. | | `method.label` | string | yes | Display label — the creator’s nickname, or e.g. "Paxum · j***@example.com", "Payout wallet · SWE", "Bank transfer · ••••1234". Never a full e-mail, IBAN or token. | | `note` | string \\| null | | Requests: the note sent with the request. Manual payouts: the note the admin recorded for the payee. Otherwise null. | | `failureMessage` | string \\| null | | Why a `failed` payout failed, as reported by the provider. Null unless `status` is `failed`. | | `invoiceNumber` | integer \\| null | | Payout invoice number once the invoice exists. The invoice itself is in the dashboard. | | `requestId` | string \\| null | | kind `payout` / `manual`: the request this payout fulfilled, if any. | | `payoutId` | string \\| null | | kind `request`: the payout or manual payout that fulfilled it, if any. | | `createdAt` | string | yes | When the payout was created or the request made. The list is ordered by this. | | `initiatedAt` | string \\| null | | When the payout was sent to the provider. | | `paidAt` | string \\| null | | When it was paid. Null unless `status` is `paid` (requests carry it on the fulfilling payout instead). | | `failedAt` | string \\| null | | When it failed. Null unless `status` is `failed`. | | `reversedAt` | string \\| null | | Set on a paid wallet load that was sent back (spendback): the money is available again. Its negative twin has `reversalOfId`. Both are hidden from GET /payouts unless includeReversed=true. | | `reversalOfId` | string \\| null | | Set on the negative row that reverses the payout with this id. | ```json { "id": "clxpo0001payout", "kind": "payout", "status": "paid", "amountCents": 52000, "currency": "USD", "side": "combined", "sides": { "creatorCents": 40000, "agencyCents": 12000, "affiliateCents": 0, "shareCents": 0 }, "method": { "type": "PAXUM_P2P", "label": "Paxum · j***@example.com" }, "note": null, "failureMessage": null, "invoiceNumber": 1042, "requestId": "clxpr0000request", "payoutId": null, "createdAt": "2026-10-15T08:00:00.000Z", "initiatedAt": "2026-10-15T08:00:05.000Z", "paidAt": "2026-10-15T08:03:41.000Z", "failedAt": null, "reversedAt": null, "reversalOfId": null } ``` ## Errors | Status | Body | When | |---|---|---| | 404 | `{"error":"Payout not found","code":"not_found"}` | Unknown id, or it belongs to another account. | | 401 | `{"error":"Unauthorized","code":"unauthorized"}` | Missing or invalid API key. | | 400 | `{"error":"X-Dropfans-Account must be an account id (from GET /api/external/agency/creators), not a username.","code":"invalid_account_header"}` | `X-Dropfans-Account` is not an account id. | | 403 | `{"error":"This key cannot act for that account.","code":"account_not_managed"}` | `X-Dropfans-Account` names an account this key cannot act for: not an agency’s own key, no ACCEPTED management, or the agency or account is suspended, banned or deleted (an unknown id gets the same answer). | | 403 | `{"error":"The agency does not have permission for this on that account.","code":"permission_denied","permission":"canViewStats"}` | With `X-Dropfans-Account`: the agency lacks `canViewStats` on that account. | ## Rate limiting Per-key fixed windows by tier (Personal 60/min · 5,000/day; approved apps 300/min · 50,000/day; Dropfans-operated integrations exempt). Read the live values from X-RateLimit-Tier, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset and their -Day variants; a 429 carries Retry-After and `{"error":"Rate limit exceeded","code":"rate_limited"}`. See [Rate limits](https://www.dropfans.io/developers/concepts/rate-limits.md). ## Code samples ### curl ```bash curl "https://www.dropfans.io/api/external/payouts/$ID" \ -H "Authorization: Bearer $DROPFANS_API_KEY" ``` ### Node ```javascript const id = '…'; // from an earlier response const res = await fetch(`https://www.dropfans.io/api/external/payouts/${id}`, { headers: { Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`, }, }); console.log(await res.json()); ``` ### Python ```python import os import requests id = "…" # from an earlier response res = requests.get( f"https://www.dropfans.io/api/external/payouts/{id}", headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"}, ) print(res.json()) ``` ## OpenAPI ```json { "method": "GET", "path": "/api/external/payouts/{id}", "operationId": "getPayout", "tags": [ "payouts" ], "summary": "One payout or payout request", "description": "One row of the history by id — a payout, a manual payout or a payout request — in any status, including failed attempts, fulfilled requests and reversal rows.\n\nThe same shape as the [payout.* webhooks](https://www.dropfans.io/developers/webhooks/overview.md) (which add `accountId`).", "parameters": [ { "name": "id", "in": "path", "required": true, "description": "Row id from the list, a webhook or POST /payouts/requests.", "schema": { "type": "string" } }, { "name": "X-Dropfans-Account", "in": "header", "required": false, "description": "Agencies only. With a verified agency’s own key, the id of a creator or AI persona the agency manages (from GET /api/external/agency/creators): the request then acts as that account, exactly as if it were sent with that account’s own key. Account ids only — usernames are refused (400 invalid_account_header). Checked on every request: the management must be ACCEPTED, nobody may be suspended, banned or deleted (else 403 account_not_managed), and the agency needs the endpoint’s permission on that account (else 403 permission_denied). Omit it to act as the key’s own account.", "schema": { "type": "string", "pattern": "^c[a-z0-9]{20,32}$" }, "example": "cmh4v2q8k0003xy9z7w6v5u4t" } ], "responses": { "200": { "description": "The row. Money in cents.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } }, "X-Dropfans-Account": { "description": "The id of the account this request acted on — the key’s own account, or the managed account named in the X-Dropfans-Account request header. Assert it when acting for several accounts.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Id of the row. Unique across the three kinds — use it with GET /api/external/payouts/{id}.", "example": "clxpo0001payout" }, "kind": { "type": "string", "description": "`payout`: sent by Dropfans (Paxum, MassPay wallet load, or settled by an admin). `manual`: paid outside the platform and recorded by an admin. `request`: a payout request the account made that has not been fulfilled into a payout yet.", "enum": [ "payout", "manual", "request" ] }, "status": { "type": "string", "description": "Requests: `requested` → `approved` → (`processing` for Paxum, from the moment they are made) → `paid`, or `rejected` / `cancelled`. Payouts: `pending` (in a batch, not sent yet) → `processing` (sent) → `paid` or `failed`; `cancelled` when an attempt was dropped. Manual payouts are always `paid`.", "enum": [ "requested", "approved", "pending", "processing", "paid", "failed", "cancelled", "rejected" ] }, "amountCents": { "type": "integer", "description": "Integer **cents**. What is paid out (negative only on a reversal row).", "example": 34210 }, "currency": { "type": "string", "description": "Always \"USD\".", "enum": [ "USD" ] }, "side": { "type": "string", "description": "Which balance it draws from: `creator` (own sales), `agency` (income from managed creators / AI personas), `affiliate` (referral commission), `share` (partner shares of other accounts’ sales), or `combined` (several sides in one transfer — see `sides`).", "example": "creator" }, "sides": { "type": "object", "properties": { "creatorCents": { "type": "integer", "description": "Creator side, cents.", "example": 34210 }, "agencyCents": { "type": "integer", "description": "Agency side, cents.", "example": 0 }, "affiliateCents": { "type": "integer", "description": "Referral commission, cents.", "example": 0 }, "shareCents": { "type": "integer", "description": "Partner shares, cents.", "example": 0 } }, "required": [ "creatorCents", "agencyCents", "affiliateCents", "shareCents" ], "description": "The amount split by side, integer cents. Adds up to `amountCents`." }, "method": { "type": [ "object", "null" ], "properties": { "type": { "type": "string", "description": "Provider method type.", "enum": [ "PAXUM_P2P", "MASSPAY", "BANK_SWIFT" ] }, "label": { "type": "string", "description": "Display label — the creator’s nickname, or e.g. \"Paxum · j***@example.com\", \"Payout wallet · SWE\", \"Bank transfer · ••••1234\". Never a full e-mail, IBAN or token.", "example": "Paxum · j***@example.com" } }, "required": [ "type", "label" ], "description": "The destination frozen when the payout or request was made, masked. Null for manual payouts." }, "note": { "type": [ "string", "null" ], "description": "Requests: the note sent with the request. Manual payouts: the note the admin recorded for the payee. Otherwise null." }, "failureMessage": { "type": [ "string", "null" ], "description": "Why a `failed` payout failed, as reported by the provider. Null unless `status` is `failed`." }, "invoiceNumber": { "type": [ "integer", "null" ], "description": "Payout invoice number once the invoice exists. The invoice itself is in the dashboard.", "example": 1042 }, "requestId": { "type": [ "string", "null" ], "description": "kind `payout` / `manual`: the request this payout fulfilled, if any." }, "payoutId": { "type": [ "string", "null" ], "description": "kind `request`: the payout or manual payout that fulfilled it, if any." }, "createdAt": { "type": "string", "description": "When the payout was created or the request made. The list is ordered by this.", "format": "date-time" }, "initiatedAt": { "type": [ "string", "null" ], "description": "When the payout was sent to the provider.", "format": "date-time" }, "paidAt": { "type": [ "string", "null" ], "description": "When it was paid. Null unless `status` is `paid` (requests carry it on the fulfilling payout instead).", "format": "date-time" }, "failedAt": { "type": [ "string", "null" ], "description": "When it failed. Null unless `status` is `failed`.", "format": "date-time" }, "reversedAt": { "type": [ "string", "null" ], "description": "Set on a paid wallet load that was sent back (spendback): the money is available again. Its negative twin has `reversalOfId`. Both are hidden from GET /payouts unless includeReversed=true.", "format": "date-time" }, "reversalOfId": { "type": [ "string", "null" ], "description": "Set on the negative row that reverses the payout with this id." } }, "required": [ "id", "kind", "status", "amountCents", "currency", "side", "sides", "createdAt" ] }, "example": { "id": "clxpo0001payout", "kind": "payout", "status": "paid", "amountCents": 52000, "currency": "USD", "side": "combined", "sides": { "creatorCents": 40000, "agencyCents": 12000, "affiliateCents": 0, "shareCents": 0 }, "method": { "type": "PAXUM_P2P", "label": "Paxum · j***@example.com" }, "note": null, "failureMessage": null, "invoiceNumber": 1042, "requestId": "clxpr0000request", "payoutId": null, "createdAt": "2026-10-15T08:00:00.000Z", "initiatedAt": "2026-10-15T08:00:05.000Z", "paidAt": "2026-10-15T08:03:41.000Z", "failedAt": null, "reversedAt": null, "reversalOfId": null } } } }, "400": { "description": "`X-Dropfans-Account` is not an account id.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message.", "example": "Rate limit exceeded" }, "code": { "type": "string", "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, rate_limited, username_required, invalid_account_header, account_not_managed, permission_denied, account_header_not_allowed, agency_key_required — plus endpoint-specific codes listed on each reference page.", "example": "rate_limited" } }, "required": [ "error", "code" ] }, "example": { "error": "X-Dropfans-Account must be an account id (from GET /api/external/agency/creators), not a username.", "code": "invalid_account_header" } } } }, "401": { "description": "Missing or invalid API key.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message.", "example": "Rate limit exceeded" }, "code": { "type": "string", "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, rate_limited, username_required, invalid_account_header, account_not_managed, permission_denied, account_header_not_allowed, agency_key_required — plus endpoint-specific codes listed on each reference page.", "example": "rate_limited" } }, "required": [ "error", "code" ] }, "example": { "error": "Unauthorized", "code": "unauthorized" } } } }, "403": { "description": "`X-Dropfans-Account` names an account this key cannot act for: not an agency’s own key, no ACCEPTED management, or the agency or account is suspended, banned or deleted (an unknown id gets the same answer). Also: With `X-Dropfans-Account`: the agency lacks `canViewStats` on that account.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message.", "example": "Rate limit exceeded" }, "code": { "type": "string", "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, rate_limited, username_required, invalid_account_header, account_not_managed, permission_denied, account_header_not_allowed, agency_key_required — plus endpoint-specific codes listed on each reference page.", "example": "rate_limited" } }, "required": [ "error", "code" ] }, "example": { "error": "This key cannot act for that account.", "code": "account_not_managed" } } } }, "404": { "description": "Unknown id, or it belongs to another account.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message.", "example": "Rate limit exceeded" }, "code": { "type": "string", "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, rate_limited, username_required, invalid_account_header, account_not_managed, permission_denied, account_header_not_allowed, agency_key_required — plus endpoint-specific codes listed on each reference page.", "example": "rate_limited" } }, "required": [ "error", "code" ] }, "example": { "error": "Payout not found", "code": "not_found" } } } }, "429": { "description": "Rate limit exceeded for the current minute or day window. Wait Retry-After seconds and retry.", "headers": { "X-RateLimit-Tier": { "description": "Rate-limit tier of the key: personal, app or first_party (first_party is unlimited).", "schema": { "type": "string", "enum": [ "personal", "app", "first_party" ] } }, "X-RateLimit-Limit": { "description": "Requests allowed per minute for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Epoch seconds when the minute window resets.", "schema": { "type": "integer" } }, "X-RateLimit-Limit-Day": { "description": "Requests allowed per UTC day for this key (absent on first_party).", "schema": { "type": "integer" } }, "X-RateLimit-Remaining-Day": { "description": "Requests left in the current UTC day window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset-Day": { "description": "Epoch seconds when the day window resets.", "schema": { "type": "integer" } }, "Retry-After": { "description": "Seconds to wait before retrying (sent with 429s).", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Human-readable message.", "example": "Rate limit exceeded" }, "code": { "type": "string", "description": "Machine-readable code: unauthorized, app_suspended, first_party_only, rate_limited, username_required, invalid_account_header, account_not_managed, permission_denied, account_header_not_allowed, agency_key_required — plus endpoint-specific codes listed on each reference page.", "example": "rate_limited" } }, "required": [ "error", "code" ] }, "example": { "error": "Rate limit exceeded", "code": "rate_limited" } } } } }, "x-codeSamples": [ { "lang": "cURL", "label": "curl", "source": "curl \"https://www.dropfans.io/api/external/payouts/$ID\" \\\n -H \"Authorization: Bearer $DROPFANS_API_KEY\"" }, { "lang": "JavaScript", "label": "Node", "source": "const id = '…'; // from an earlier response\n\nconst res = await fetch(`https://www.dropfans.io/api/external/payouts/${id}`, {\n headers: {\n Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,\n },\n});\nconsole.log(await res.json());" }, { "lang": "Python", "source": "import os\nimport requests\n\nid = \"…\" # from an earlier response\n\nres = requests.get(\n f\"https://www.dropfans.io/api/external/payouts/{id}\",\n headers={\"Authorization\": f\"Bearer {os.environ['DROPFANS_API_KEY']}\"},\n)\nprint(res.json())" } ], "x-dropfans-docs": "https://www.dropfans.io/developers/reference/get-payout", "x-dropfans-agency-permission": "canViewStats" } ``` --- Previous: [Payout history (paginated)](https://www.dropfans.io/developers/reference/list-payouts.md) · Next: [Payout methods (masked)](https://www.dropfans.io/developers/reference/list-payout-methods.md) · All pages: [llms.txt](https://www.dropfans.io/developers/llms.txt)