What happened
Every payoutpurpose except intercompany and prefunding requires at least one supporting document, uploaded via POST /v2/documents with purpose=transaction_support. A prefunding payout never requires one. DOCUMENTATION_REQUIRED (HTTP 422) is the error code Conduit defines for a payout submitted without a required document.
Organizations set up for post-acceptance documentation collection do not get this error on a payout that attaches no document — neither on
POST /v2/payouts nor on an order’s autoPayout leg. Conduit accepts the payout, holds it at stage: awaiting_customer_action with hasRfi: true, and asks for the document through a request for information; the payout is rejected if the document does not arrive before the request’s due date. An organization with no portal user has nobody to receive the request, so it still gets this error even with post-acceptance collection. Every other organization gets this error and retries with the document attached. See Send a payout.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
You may reuse the same
Idempotency-Key for the corrected resubmission. This response is a 422, so nothing was committed and the corrected body is evaluated as a fresh attempt. Keep that 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