API reference
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.
View as MarkdownUpdated Oct 30, 2026
GET
/api/external/payouts/{id}NewOne 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 (which add accountId).
Authentication
Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.
An agency's own key can call this for a creator it manages by adding X-Dropfans-Account: <account id> (needs canViewStats). See Agencies.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | Row id from the list, a webhook or POST /payouts/requests. |
Responses
200The row. Money in cents.
| Name | Type | Description | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
id | string | Id of the row. Unique across the three kinds — use it with GET /api/external/payouts/{id}. | ||||||||||||
kind | string | 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.One of: payout, manual, request | ||||||||||||
status | string | 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.One of: requested, approved, pending, processing, paid, failed, cancelled, rejected | ||||||||||||
amountCents | integer | Integer **cents**. What is paid out (negative only on a reversal row). | ||||||||||||
currency | string | Always "USD". One of: USD | ||||||||||||
side | string | 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 | The amount split by side, integer cents. Adds up to amountCents.Show child attributes
| ||||||||||||
method | object | null | The destination frozen when the payout or request was made, masked. Null for manual payouts.Show child attributes
| ||||||||||||
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 | When the payout was created or the request made. The list is ordered by this. Format: date-time | ||||||||||||
initiatedAt | string | null | When the payout was sent to the provider. Format: date-time | ||||||||||||
paidAt | string | null | When it was paid. Null unless status is paid (requests carry it on the fulfilling payout instead).Format: date-time | ||||||||||||
failedAt | string | null | When it failed. Null unless status is failed.Format: date-time | ||||||||||||
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.Format: date-time | ||||||||||||
reversalOfId | string | null | Set on the negative row that reverses the payout with this id. |
Example response
{
"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
Every response carries the X-RateLimit-Tier header and, on limited tiers, the per-minute and per-day trios — read X-RateLimit-Remaining and X-RateLimit-Reset instead of hardcoding limits. Details in Rate limits.
Code samples
curl "https://www.dropfans.io/api/external/payouts/$ID" \
-H "Authorization: Bearer $DROPFANS_API_KEY"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());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())Questions? [email protected]