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.
Whether a payout that attaches no document gets this error is set per organization, on
POST /v2/payouts and on an order’s autoPayout leg alike. Where Conduit collects the document before it accepts the payout, you get this error and retry with the document attached. Where Conduit collects it after acceptance, it 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 always gets this error. 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