Add Supporting Documents - Yala Payout APIs

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.

Each URL in documents must be a documentUrl from POST /documents/upload-url after you PUT the file to S3. Do not send file bytes to this PATCH endpoint. See Uploading Supporting Documents.If we have requested additional documents (ADDITIONAL_INFO_REQUIRED) and you need to send more than one file, merge them into one PDF before uploading to S3, then pass that documentUrl in this PATCH request.

Requirements:

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

Headers

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"
}

Solution: Documents can only be added when payout status is 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"
}

Solution: Remove some existing documents or add fewer documents. Maximum 5 documents total per payout.

400 Bad Request - Invalid URL Format

{
  "statusCode": 400,
  "message": "documents[0] must be a URL address",
  "error": "VALIDATION_ERROR"
}

Solution: Ensure all document URLs are valid HTTPS URLs (e.g., 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"
}

Solution: Verify the payout ID is correct and belongs to your business.

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

​Overview

​Request

​Path Parameters

​Headers

​Request Body

​Request Fields

​Response

​Response Fields

​Error Responses

​400 Bad Request - Invalid Payout Status

​400 Bad Request - Maximum Documents Exceeded

​400 Bad Request - Invalid URL Format

​404 Not Found

​401 Unauthorized

​Usage Example

​Notes

Overview

Request

Path Parameters

Headers

Request Body

Request Fields

Response

Response Fields

Error Responses

400 Bad Request - Invalid Payout Status

400 Bad Request - Maximum Documents Exceeded

400 Bad Request - Invalid URL Format

404 Not Found

401 Unauthorized

Usage Example

Notes