API reference
Change a payout method
Rename a payout method, make it the default (or stop using it as the default), or point a Paxum method at another Paxum e-mail.
View as MarkdownUpdated Oct 30, 2026
PATCH
/api/external/payouts/methods/{id}NewRename a payout method, make it the default (or stop using it as the default), or point a Paxum method at another Paxum e-mail.
Send only what changes. Any other field is refused with 400 unknown_field. A new paxumEmail is looked up again like on create (422 paxum_account_not_active unless active) and clears the method's earlier Paxum identity check, which was for the old account. isDefault: true moves the default here; isDefault: false leaves the account without a default method.
The key's own account only, after the ID check.
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 method id (from GET /payouts/methods). |
Request body
Content type: application/json
| Name | Type | Required | Description |
|---|---|---|---|
nickname | string | null | Optional | New label; null or "" clears it. Max length: 100 |
isDefault | boolean | Optional | true: make it the default. false: no longer the default. |
paxumEmail | string | Optional | PAXUM_P2P only: the new Paxum e-mail.Format: email |
Make it the default
{
"isDefault": true
}Responses
200The updated method.
| Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
method | PayoutMethodSummary | The method, masked.Show child attributes
|
Example response
{
"method": {
"id": "clxpm0002method",
"type": "PAXUM_P2P",
"isDefault": true,
"nickname": "Main Paxum",
"label": "Main Paxum",
"holderType": "INDIVIDUAL",
"createdAt": "2026-10-30T10:00:00.000Z",
"paxum": {
"email": "j***@example.com",
"lookupStatus": "active",
"verificationStatus": null
},
"masspay": null,
"bank": null
}
}Errors
| Status | Body | When |
|---|---|---|
| 400 | {"error":"Unknown field: bankIban. Allowed: nickname, isDefault, paxumEmail.","code":"unknown_field"} | A field that cannot be changed (`invalid_nickname`, `invalid_is_default`, `invalid_paxum_email` for bad values). |
| 400 | {"error":"paxumEmail can only be changed on a PAXUM_P2P method.","code":"field_not_applicable"} | `paxumEmail` on a MassPay wallet. |
| 400 | {"error":"Invalid JSON body"} | The body is not valid JSON (`invalid_body` when it is not an object). |
| 401 | {"error":"Unauthorized","code":"unauthorized"} | Missing or invalid API key. |
| 403 | {"error":"Verify your identity (KYC) before setting up payouts.","code":"kyc_required"} | The account has not passed the ID check. |
| 403 | {"error":"Payout methods need the account’s own key — a key an agency minted for a managed account cannot read or change where payouts go.","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-method endpoints are open to Dropfans-operated integrations only. |
| 404 | {"error":"Not found","code":"not_found"} | Unknown id, or it belongs to another account. |
| 422 | {"error":"This Paxum account is not active. Activate it at Paxum first.","code":"paxum_account_not_active","lookupStatus":"inactive"} | The new e-mail is not an active Paxum account. |
| 502 | {"error":"Could not reach Paxum to check the e-mail. Try again in a moment.","code":"paxum_unavailable"} | The Paxum lookup failed. Retry. |
| 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 change where a creator it manages is paid. |
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 PATCH "https://www.dropfans.io/api/external/payouts/methods/$ID" \
-H "Authorization: Bearer $DROPFANS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"isDefault": true
}'const id = '…'; // from an earlier response
const res = await fetch(`https://www.dropfans.io/api/external/payouts/methods/${id}`, {
method: 'PATCH',
headers: {
Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"isDefault": true
}),
});
console.log(await res.json());import os
import requests
id = "…" # from an earlier response
res = requests.patch(
f"https://www.dropfans.io/api/external/payouts/methods/{id}",
headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
json={
"isDefault": True,
},
)
print(res.json())Questions? [email protected]