Documents & Compliance

Cross-border payouts carry two kinds of supporting documents. Both are uploaded once with Upload Document and referenced by the returned key.

Document	What it proves	Where it goes	When it is required
Sender compliance document	Who the sender is	`destination.sender.complianceDocument.proofOfIdentity` on the beneficiary	Every SWIFT (USD) beneficiary, and beneficiaries paid in INR, AED, CNY, GBP or EUR
Payout document (invoice)	Why the money is being sent	`receiptRef` on the payout, or the Attach Payout Document endpoint	Every business transaction: B2B, B2C and C2B

Sender compliance document

The sender is the person or company on whose behalf you send the funds (destination.sender). Their identity document is bound to the beneficiary and is forwarded to the payout partner with every transfer to that beneficiary, including individual-to-individual transfers.

`sender.type`	Document to upload
`INDIVIDUAL`	A government-issued identity document: passport, national ID card or driving licence. It must match `sender.idType` and `sender.idNumber`.
`BUSINESS`	The business registration document: certificate of incorporation or certificate of registration. It must match `sender.businessRegistrationNumber` and `sender.businessRegistrationType`.

How to attach it:

Call Upload Document with the file. Keep the key from the response.
Create the beneficiary with destination.sender.complianceDocument.proofOfIdentity set to that key. The same key can be reused for every beneficiary created for the same sender.
Brails verifies the key belongs to your business and that the file exists before the beneficiary is accepted.

Sender with compliance document

"sender": {
  "type": "BUSINESS",
  "accountName": "Acme Trading Ltd",
  "businessRegistrationNumber": "RC123456",
  "businessRegistrationType": "LLC",
  "businessRegistrationIssueDate": "2019-03-01",
  "complianceDocument": {
    "proofOfIdentity": "documents/45422f21-9a0e-479e-9e10-615556448a78/7b1c6e2a-3f0d-4c8e-9a51-2d6f8e4b9c10.pdf"
  }
}

📘

proofOfIdentity is the only key accepted inside complianceDocument today, for both individual and business senders. Sender details cannot be changed on an existing beneficiary; to send from a different sender, create a new beneficiary with that sender's document.

Payout document (invoice)

A payout document (invoice, contract or receipt) justifies the transfer. Whether it is required depends on the transaction type, derived from sender.type and beneficiary.type on the beneficiary:

Sender	Beneficiary	Transaction type	Payout document
`BUSINESS`	`BUSINESS`	B2B	✅ Required
`BUSINESS`	`INDIVIDUAL`	B2C	✅ Required
`INDIVIDUAL`	`BUSINESS`	C2B	✅ Required
`INDIVIDUAL`	`INDIVIDUAL`	C2C	Not required

A party whose type cannot be determined is treated as a business, so the document is required.

Two ways to attach it:

At initialization (recommended). Upload the document, then pass the key as receiptRef in Initiate Payout. If the payout needs a document and receiptRef is empty, the request fails with 422 document_required and nothing is created.
After initialization. Initiate the payout, then call Attach Payout Document with the file before finalizing. The document is verified again at finalize and before the transfer is sent to the partner.

China bank payouts (except individual-to-individual) and India payouts from a business sender also require a payout document, regardless of rail.

File constraints

Constraint	Value
Formats	`pdf`, `jpg`, `jpeg`, `png` recommended. `doc` and `docx` are accepted by the upload endpoint but may be rejected by the payout partner.
Size	10 MB maximum at upload; keep documents under 5 MB so the payout partner accepts them.
Reuse	A compliance document key can be reused across beneficiaries. A payout document should be specific to the transfer.

Errors and recovery

Status	Message	Step	What to do
400	`file is required`	Upload	Send the file in the `file` multipart part.
400	`this endpoint does not accept <type> files`	Upload	Convert the document to `pdf`, `jpg`, `jpeg` or `png` and upload again.
413	`file exceeds the maximum allowed size`	Upload	Reduce the file below 10 MB (ideally 5 MB) and upload again.
403	`Upload does not belong to this company`	Beneficiary / payout	The key was minted under another business or is malformed. Upload the file with your own secret key and use that key.
400	`Failed to create beneficiary`	Beneficiary	`complianceDocument.proofOfIdentity` does not reference an existing upload. Re-upload and retry with the new key.
422	`document_required:Please upload required document to proceed with this transaction`	Initiate / finalize	The transaction type needs an invoice. Upload it and retry with `receiptRef`, or attach it to the transaction and finalize again.
422	`Please upload the required document before processing this transaction`	Processing	The payout reached processing without a document. Attach one with Attach Payout Document, then finalize again.
422	`Transaction document was not found in storage`	Attach / processing	The reference points to a missing object. Upload the document again and re-attach.
404	`Transaction not found`	Attach	The transaction id is wrong or belongs to another business.
400	`Transaction has no payout to attach a document to`	Attach	The transaction is not a payout, or has not been initialized. Initialize the payout first.

⚠️

Documents are checked at three points: when the beneficiary is created, when the payout is initialized or finalized, and again just before the transfer is handed to the payout partner. A payout that fails the last check is not processed until a valid document is attached.

Transfers Collections