Add a Paxum payout method
Add a Paxum account as a payout method — what "Add Paxum" does in the dashboard, with a stricter e-mail check.
/api/external/payouts/methodsNewAdd a Paxum account as a payout method — what "Add Paxum" does in the dashboard, with a stricter e-mail check.
The e-mail is looked up at Paxum and must be an active Paxum account: unknown or inactive accounts are refused with 422 paxum_account_not_active (the dashboard shows that on the card; an integration has nobody to show it to). If Paxum cannot be reached the answer is 502 paxum_unavailable — retry.
Safe to retry, no Idempotency-Key needed: adding an e-mail the account already has (case-insensitive) returns that existing method with 200 and Idempotent-Replayed: true instead of a duplicate; nickname / isDefault are then not applied (use PATCH).
isDefault: true makes it the method payouts go to. A MassPay wallet is set up with POST /payouts/masspay/profile instead.
The key's own account only (X-Dropfans-Account and agency-minted keys are refused) and only after the ID check (403 kyc_required).
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.
Request body
Content type: application/json
| Name | Type | Required | Description |
|---|---|---|---|
type | string | Required | The method type. Only PAXUM_P2P is created here.One of: PAXUM_P2P |
paxumEmail | string | Required | The e-mail of the creator’s Paxum account. Never returned unmasked. Format: email Max length: 254 |
nickname | string | null | Optional | The creator’s own label, shown instead of the masked e-mail. Max length: 100 |
isDefault | boolean | Optional | Make it the default payout method. Default: false |
{
"type": "PAXUM_P2P",
"paxumEmail": "[email protected]",
"nickname": "Main Paxum",
"isDefault": true
}Responses
| Name | Type | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
method | PayoutMethodSummary | The method, masked.Show child attributes
|
{
"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":"paxumEmail is not a valid email","code":"invalid_paxum_email"} | `paxumEmail` missing or not an e-mail. |
| 400 | {"error":"type must be \"PAXUM_P2P\".","code":"unsupported_type"} | `type` missing or another type (MASSPAY: use POST /payouts/masspay/profile). |
| 400 | {"error":"Unknown field: iban. Allowed: type, paxumEmail, nickname, isDefault.","code":"unknown_field"} | A field that is not in the table (`invalid_nickname` / `invalid_is_default` for a wrong type or length). |
| 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. |
| 409 | {"error":"Another payout operation is running for this account. Try again in a moment.","code":"payout_busy"} | Another payout operation holds the account’s payout lock. Retry. |
| 422 | {"error":"No Paxum account uses this e-mail. Check it, or create the Paxum account first.","code":"paxum_account_not_active","lookupStatus":"not_found"} | The e-mail is not an active Paxum account (`lookupStatus`: `not_found` or `inactive`). |
| 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 POST "https://www.dropfans.io/api/external/payouts/methods" \
-H "Authorization: Bearer $DROPFANS_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "PAXUM_P2P",
"paxumEmail": "[email protected]",
"nickname": "Main Paxum",
"isDefault": true
}'const res = await fetch(`https://www.dropfans.io/api/external/payouts/methods`, {
method: 'POST',
headers: {
Authorization: `Bearer ${process.env.DROPFANS_API_KEY}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({
"type": "PAXUM_P2P",
"paxumEmail": "[email protected]",
"nickname": "Main Paxum",
"isDefault": true
}),
});
console.log(await res.json());import os
import requests
res = requests.post(
"https://www.dropfans.io/api/external/payouts/methods",
headers={"Authorization": f"Bearer {os.environ['DROPFANS_API_KEY']}"},
json={
"type": "PAXUM_P2P",
"paxumEmail": "[email protected]",
"nickname": "Main Paxum",
"isDefault": True,
},
)
print(res.json())Questions? [email protected]