Skip to main content

​
Overview

Yala does not accept invoice file bytes on the payout API. You:
  1. Call POST /documents/upload-url (JSON: filename + content type).
  2. PUT the invoice file to the returned uploadUrl (Amazon S3). Valid for 15 minutes.
  3. 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

FieldUse
uploadUrlOne-time S3 PUT. Expires in 15 minutes.
documentUrlPass 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)

​
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

  1. POST /initiate without supportingDocument. Save payout id.
  2. Same upload-url + S3 PUT as above.
  3. 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

MistakeFix
POST file to Yala upload-url or initiateFile goes to S3 via uploadUrl only
Pass uploadUrl to initiate/PATCHUse documentUrl
Skip the S3 PUTCompliance cannot see the invoice
Expired uploadUrlCall upload-url again (15 min TTL)