> ## Documentation Index
> Fetch the complete documentation index at: https://docs.useyala.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Uploading Supporting Documents

> How to attach invoices to payout API payouts.

## 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`**.

```mermaid theme={null}
sequenceDiagram
  participant Partner as Partner backend
  participant Yala as Yala API
  participant S3 as Yala S3 bucket

  Partner->>Yala: POST /documents/upload-url
  Yala-->>Partner: uploadUrl, documentUrl
  Partner->>S3: PUT invoice to uploadUrl
  Partner->>Yala: initiate or PATCH with documentUrl
```

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

## 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

<Note>
  **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.
</Note>

### 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**

```http theme={null}
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**

```bash theme={null}
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**

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

See [Initiate Payout](/api-reference/endpoint/initiate).

## 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](/api-reference/endpoint/add-documents).

## Testing with Postman

Import the [Postman collection](/guides/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](https://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)                     |

## Related

* [Get Document Upload URL](/api-reference/endpoint/upload-document-url)
* [Initiate Payout](/api-reference/endpoint/initiate)
* [Add Supporting Documents](/api-reference/endpoint/add-documents)