What happened
You submitted a payout whosepurpose requires supporting documentation, but the documents array carried no valid supporting document. Every purpose except intercompany and prefunding requires at least one document that was uploaded via POST /v2/documents with purpose=transaction_support (a prefunding payout requires one only when a documentation policy applies to its amount). This returns HTTP 422 with error code DOCUMENTATION_REQUIRED.
Common causes
- Missing
documents—purposeis present butdocumentsis empty or absent - Wrong document purpose — the document exists but was uploaded with a purpose other than
transaction_support
purpose: intercompany payouts (a separate recipient whitelisting gate applies) and, by default, not to purpose: prefunding payouts. A missing or invalid purpose value returns HTTP 400 VALIDATION_ERROR, not this error.
Recovery
1. Upload a supporting document with purpose transaction_support Documents are uploaded as multipart/form-data. Thefile field must be a valid PDF (binary, with %PDF- magic bytes):
id (format doc_*).
2. Resubmit the payout with purpose and documents
Use a new
Idempotency-Key for the corrected resubmission — attaching the document changes the request body, and the original key is bound to the no-document attempt, so reusing it returns 409 IDEMPOTENCY_KEY_CONFLICT. Keep that new key for any further retries of the corrected payout, so a lost response replays the one accepted payout instead of creating a second one.Prevention
- Always upload documents with
purpose=transaction_supportbefore referencing them in a payout - Include the returned
doc_*id in the payoutdocumentsarray when submitting a payout whose purpose requires documentation - For intercompany transfers, use
purpose: intercompanyand pre-register the recipient viaPOST /v2/customers/:id/whitelist-recipientsinstead
Related endpoints
- POST /v2/documents — upload a supporting document
- POST /v2/payouts — create a payout