Skip to main content

​
Overview

Adds additional supporting documents to an existing payout. Documents are stored with UUID identifiers and can be added multiple times (up to 5 documents total per payout). 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
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

ParameterTypeRequiredDescription
idstring (UUID)YesPayout identifier

​
Headers

HeaderRequiredDescription
x-api-keyYesYour API key

​
Request Body

{
  "documents": [
    "https://yala-staging.s3.us-east-1.amazonaws.com/1769262715606-Logo.png"
  ]
}

​
Request Fields

FieldTypeRequiredDescription
documentsarray of strings (URLs)YesArray of supporting document URLs (HTTPS required). 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

FieldTypeDescription
payoutIdstring (UUID)Payout identifier
totalDocumentsnumberTotal number of documents after adding
documentsarrayAll supporting documents for this payout
documents[].idstring (UUID)Document UUID identifier
documents[].urlstring (URL)Document URL
documents[].uploadedAtstring (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 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 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