Overview
Retrieve payout status and details by ID for the authenticated business. Returns conversion information, exchange rates, fees, timestamps, and attached supporting documents (from creation or added via PATCH /documents).
Request
GET /v1/payout-api/payouts/{id} HTTP/1.1
Host: gateway.staging.useyala.com
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 |
Response
{
"id": "payout-id-uuid",
"payoutRef": "PAY-2024-001",
"businessId": "business-id-uuid",
"sourceAmount": 10000,
"sourceCurrency": "NGN",
"destinationAmount": 42.5,
"destinationCurrency": "CNY",
"status": "PENDING",
"method": "ALIPAY",
"transactionFees": 0,
"narration": "Payment for services",
"exchangeRate": 235.0,
"createdAt": "2024-01-20T10:00:00Z",
"updatedAt": "2024-01-20T10:00:00Z",
"supportingDocuments": [
{
"id": "550e8400-e29b-41d4-a716-446655440000",
"url": "https://example.com/document.pdf",
"uploadedAt": "2024-01-20T10:00:00Z"
}
]
}
Response Fields
| Field | Type | Description |
|---|
id | string (UUID) | Payout identifier |
payoutRef | string | Human-readable payout reference |
sourceAmount | number | Amount debited from source wallet |
sourceCurrency | string | Source currency |
destinationAmount | number | Amount sent to beneficiary |
destinationCurrency | string | Destination currency |
status | string | One of: PENDING, PROCESSING, SUCCESSFUL, FAILED, REJECTED. Same values as webhooks. |
method | string | Payment method used |
transactionFees | number | Transaction fees |
exchangeRate | number | Exchange rate used for conversion |
createdAt | string (ISO 8601) | Payout creation timestamp |
updatedAt | string (ISO 8601) | Last update timestamp |
supportingDocuments | array | Attached supporting documents (from initiation or PATCH /documents). Each item has id, url, and uploadedAt. |
Error Responses
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
const response = await fetch(
`https://gateway.staging.useyala.com/v1/payout-api/payouts/${payoutId}`,
{
headers: {
'x-api-key': apiKey,
},
}
);
const payout = await response.json();
console.log(`Status: ${payout.status}, Amount: ${payout.destinationAmount} ${payout.destinationCurrency}`);
Use this endpoint to check payout status after creation or to display payout details in your dashboard. Alternatively, subscribe to webhook notifications to receive real-time status updates.
Webhooks
Instead of polling this endpoint, you can subscribe to webhook notifications for real-time status updates:
- Activate webhooks in your Yala dashboard
- Configure your webhook endpoint URL
- Receive notifications when payout status changes
The webhook payload includes the payout id (matching the id field in this response) so you can identify which payout was updated.
