API reference
Cancel a payout request
Cancel one of the account's payout requests while it is still `requested`.
View as MarkdownUpdated Oct 30, 2026
POST
/api/external/payouts/requests/{id}/cancelNewCancel one of the account's payout requests while it is still requested.
Its side can be requested again straight away. Once a request is approved or processing (Paxum requests are processing from the moment they are made — the mass-payout file may already be paid) it is on its way and can no longer be cancelled; nor once it is paid, rejected or cancelled. The answer is then 409 request_not_cancellable — so repeating a cancel is harmless.
The key's own account only (X-Dropfans-Account and agency-minted keys are refused).
Dropfans-operated integrations only, for now
At launch this endpoint answers 403 first_party_only to every other app. The read endpoints of this group are open to every key.
Authentication
Send the creator's API key as a bearer token: Authorization: Bearer dpfn_…. See Authentication & API keys.
Path parameters
| Name | Type | Required | Description |
|---|---|---|---|
id | string | Required | The request id (kind: "request"). |
Responses
200The cancelled request.
| 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": "clxpr0001request",
"kind": "request",
"status": "cancelled",
"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
}Errors
| Status | Body | When |
|---|---|---|
| 401 | {"error":"Unauthorized","code":"unauthorized"} | Missing or invalid API key. |
| 403 | {"error":"Payout requests need the account’s own key — a key an agency minted for a managed account cannot request or cancel payouts.","code":"agency_key_not_allowed"} | The key was minted by an agency for an account it manages. |
| 403 | {"error":"This endpoint is only available to Dropfans-operated integrations.","code":"first_party_only"} | During launch, payout requests are open to Dropfans-operated integrations only. |
| 404 | {"error":"Not found","code":"not_found"} | Unknown id, or it belongs to another account. |
| 409 | {"error":"This request is already being paid out and can no longer be cancelled.","code":"request_not_cancellable"} | Approved or processing (on its way), or already paid, rejected or cancelled. |
| 400 | {"error":"This endpoint only acts as the key’s own account — send it without X-Dropfans-Account.","code":"account_header_not_allowed"} | `X-Dropfans-Account` names another account. An agency can never request or cancel a payout for a creator it manages. |
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 -X POST "https://www.dropfans.io/api/external/payouts/requests/$ID/cancel" \
-H "Authorization: Bearer $DROPFANS_API_KEY"const id = '…'; // from an earlier response
const res = await fetch(`https://www.dropfans.io/api/external/payouts/requests/${id}/cancel`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
},
});
console.log(await res.json());import os
import requests
id = "…" # from an earlier response
res = requests.post(
f"https://www.dropfans.io/api/external/payouts/requests/{id}/cancel",
headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
)
print(res.json())Questions? [email protected]