Uploading Supporting Documents

Overview

Yala does not accept invoice file bytes on the payout API. You:

Call POST /documents/upload-url (JSON: filename + content type).
PUT the invoice file to the returned uploadUrl (Amazon S3). Valid for 15 minutes.
Pass the returned documentUrl on POST /initiate (supportingDocument) or PATCH /:id/documents.

Most payouts need an invoice attached before they can be processed. Withdrawals (to your business account or a UBO account) are the exception.

URLs

Field	Use
`uploadUrl`	One-time S3 PUT. Expires in 15 minutes.
`documentUrl`	Pass to Yala on initiate or PATCH. Do not use for upload.

Formats and limits

PDF, JPEG, or PNG (application/pdf, image/jpeg, image/png)
Max 10 MB per file, max 5 files per payout (initiate + PATCH combined)

Multiple files

Recommendation: If you need to send more than one supporting document, merge them into a single PDF before uploading to S3. Then pass that one documentUrl when you initiate the payout or call PATCH.

At payout creation

POST /initiate accepts one supportingDocument URL. If your payment is backed by several files (for example, an invoice and a contract), combine them into one PDF first, upload it via the upload-url flow, and pass the resulting documentUrl on initiate.

When we request additional documents

If a payout is in ADDITIONAL_INFO_REQUIRED status, send further supporting documents with PATCH /:id/documents. Use the same upload-url + S3 PUT flow. If you have multiple files to send, merge them into one PDF before uploading to S3, then include that documentUrl in the PATCH documents array.

Attach at payout creation

1. Get upload URL

POST /v1/payout-api/payouts/documents/upload-url
Content-Type: application/json
x-api-key: <YOUR_API_KEY>

{ "filename": "invoice.pdf", "contentType": "application/pdf" }

2. Upload to S3

curl -X PUT '<uploadUrl>' \
  -H 'Content-Type: application/pdf' \
  --data-binary @invoice.pdf

Use the headers from the upload-url response on your PUT. Expect HTTP 200 from S3. 3. Create payout

{
  "sourceAmount": 10000,
  "sourceCurrency": "NGN",
  "destinationCurrency": "CNY",
  "destinationCountryCode": "CHN",
  "method": "ALIPAY",
  "beneficiary": { },
  "narration": "Payment for services",
  "supportingDocument": "<documentUrl>"
}

See Initiate Payout.

Attach after payout creation

POST /initiate without supportingDocument. Save payout id.
Same upload-url + S3 PUT as above.
PATCH /v1/payout-api/payouts/{id}/documents with { "documents": ["<documentUrl>"] }.

Allowed until status is SUCCESSFUL, FAILED, or REJECTED. See Add Supporting Documents.

Testing with Postman

Import the Postman collection. Run Get Document Upload URL, then Upload File to S3, then Initiate Payout (uses {{documentUrl}}). Details for the S3 PUT request are in the collection description.

Viewing invoices

Files are private. View them in the dashboard at app.useyala.com by opening the payout.

Common mistakes

Mistake	Fix
Sending several separate files when one PDF would do	Merge multiple documents into one PDF before S3 upload
POST file to Yala upload-url or initiate	File goes to S3 via `uploadUrl` only
Pass `uploadUrl` to initiate/PATCH	Use `documentUrl`
Skip the S3 PUT	Compliance cannot see the invoice
Expired `uploadUrl`	Call upload-url again (15 min TTL)

Start Here

Concepts

Uploading Supporting Documents

Overview

URLs

Formats and limits

Multiple files

At payout creation

When we request additional documents

Attach at payout creation

Attach after payout creation

Testing with Postman

Viewing invoices

Common mistakes

​Overview

​URLs

​Formats and limits

​Multiple files

​At payout creation

​When we request additional documents

​Attach at payout creation

​Attach after payout creation

​Testing with Postman

​Viewing invoices

​Common mistakes

​Related

Overview

URLs

Formats and limits

Multiple files

At payout creation

When we request additional documents

Attach at payout creation

Attach after payout creation

Testing with Postman

Viewing invoices

Common mistakes

Related