Overview
Adds supporting documents to an existing payout. Use this when you initiated without a document or need to add more files later.
Most payouts need at least one supporting document before they can be processed. Withdrawals to your business account or a UBO’s account are the exception.
- Payout must exist and belong to your business
- Payout status must NOT be
SUCCESSFUL, FAILED, or REJECTED
- Maximum 5 documents total per payout
- All document URLs must be HTTPS
- Accepted file formats: PDF, JPEG/JPG, and PNG only
Behavior:
- Documents are stored with UUID identifiers
- Duplicate URLs are automatically filtered out
- Returns all documents (existing + newly added)
Request
PATCH /v1/payout-api/payouts/{id}/documents HTTP/1.1
Host: gateway.staging.useyala.com
Content-Type: application/json
x-api-key: <YOUR_API_KEY>
Path Parameters
| Parameter | Type | Required | Description |
|---|
id | string (UUID) | Yes | Payout identifier |
| Header | Required | Description |
|---|
x-api-key | Yes | Your API key |
Request Body
{
"documents": [
"https://yala-payout-api-docs-staging.s3.us-east-1.amazonaws.com/staging/payout-api/<businessId>/<documentId>/invoice.pdf"
]
}
Request Fields
| Field | Type | Required | Description |
|---|
documents | array of strings (URLs) | Yes | Array of supporting document URLs (HTTPS required). Accepted formats: PDF, JPEG/JPG, PNG. Maximum 5 documents total per payout. |
Response
{
"payoutId": "123e4567-e89b-12d3-a456-426614174000",
"totalDocuments": 3,
"documents": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://yala-staging.s3.us-east-1.amazonaws.com/1769262715606-Logo.png",
"uploadedAt": "2024-01-21T12:00:00Z"
},
{
"id": "660e8400-e29b-41d4-a716-446655440001",
"url": "https://yala-staging.s3.us-east-1.amazonaws.com/1769262715606-Logo.png",
"uploadedAt": "2024-01-21T12:05:00Z"
},
{
"id": "770e8400-e29b-41d4-a716-446655440002",
"url": "https://yala-staging.s3.us-east-1.amazonaws.com/1769262715606-Logo.png",
"uploadedAt": "2024-01-21T12:10:00Z"
}
]
}
Response Fields
| Field | Type | Description |
|---|
payoutId | string (UUID) | Payout identifier |
totalDocuments | number | Total number of documents after adding |
documents | array | All supporting documents for this payout |
documents[].id | string (UUID) | Document UUID identifier |
documents[].url | string (URL) | Document URL |
documents[].uploadedAt | string (ISO 8601) | Upload timestamp |
Error Responses
400 Bad Request - Invalid Payout Status
{
"statusCode": 400,
"message": "Cannot add documents to payout with status: SUCCESSFUL",
"error": "INVALID_PAYOUT_STATUS"
}
PENDING, ADDITIONAL_INFO_REQUIRED, or PROCESSING. Once a payout is SUCCESSFUL, FAILED, or REJECTED, documents cannot be added.
400 Bad Request - Maximum Documents Exceeded
{
"statusCode": 400,
"message": "Maximum 5 documents allowed. Current: 4, Adding: 2",
"error": "MAX_DOCUMENTS_EXCEEDED"
}
{
"statusCode": 400,
"message": "documents[0] must be a URL address",
"error": "VALIDATION_ERROR"
}
https://yala-staging.s3.us-east-1.amazonaws.com/1769262715606-Logo.png).
404 Not Found
{
"statusCode": 404,
"message": "Payout not found or not associated with your business",
"error": "PAYOUT_NOT_FOUND"
}
401 Unauthorized
{
"statusCode": 401,
"message": "Unauthorized"
}
Usage Example
// Add supporting documents to an existing payout
const response = await fetch(
'https://gateway.staging.useyala.com/v1/payout-api/payouts/{payoutId}/documents',
{
method: 'PATCH',
headers: {
'Content-Type': 'application/json',
'x-api-key': apiKey,
},
body: JSON.stringify({
documents: [
'https://yala-staging.s3.us-east-1.amazonaws.com/1769262715606-Logo.png',
],
}),
}
);
const result = await response.json();
console.log(`Total documents: ${result.totalDocuments}`);
console.log(`Document IDs: ${result.documents.map(d => d.id).join(', ')}`);
Notes
- Status Restrictions: Documents can only be added when payout status is
PENDING, ADDITIONAL_INFO_REQUIRED, or PROCESSING (not SUCCESSFUL, FAILED, or REJECTED)
- Maximum Documents: 5 documents total per payout
- Duplicate Filtering: Duplicate URLs are automatically filtered out
- UUID Identifiers: Each document is assigned a UUID for tracking
- HTTPS Required: All document URLs must use HTTPS protocol
- Accepted Formats: Only PDF (
.pdf), JPEG (.jpeg, .jpg), and PNG (.png) files are accepted
