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

# Get Payout by ID

> Retrieve detailed information about a specific payout.

## Overview

Retrieve payout status and details by ID for the authenticated business. Returns conversion information, exchange rates, fees, timestamps, **attached supporting documents** (from creation or added via PATCH `/documents`), and **requested information** when compliance needs more from you (`ADDITIONAL_INFO_REQUIRED`).

## Request

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

### Headers

| Header      | Required | Description  |
| ----------- | -------- | ------------ |
| `x-api-key` | Yes      | Your API key |

## Response

```json theme={null}
{
  "id": "payout-id-uuid",
  "payoutRef": "PAY-2024-001",
  "sourceAmount": 10000,
  "sourceCurrency": "NGN",
  "destinationAmount": 42.5,
  "destinationCurrency": "CNY",
  "status": "ADDITIONAL_INFO_REQUIRED",
  "method": "ALIPAY",
  "transactionFees": 0,
  "exchangeRate": 235.0,
  "createdAt": "2024-01-20T10:00:00Z",
  "updatedAt": "2024-01-21T09:00:00Z",
  "informationRequests": [
    {
      "title": "Invoice copy",
      "description": "Please provide a clearer invoice showing beneficiary name",
      "type": "FILE"
    }
  ],
  "supportingDocuments": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "url": "https://example.com/document.pdf",
      "uploadedAt": "2024-01-20T10:00:00Z"
    }
  ]
}
```

When submitted additional information is under review internally, `status` is `PENDING` and `statusDetail` is `ADDITIONAL_INFO_UNDER_REVIEW`:

```json theme={null}
{
  "id": "payout-id-uuid",
  "status": "PENDING",
  "statusDetail": "ADDITIONAL_INFO_UNDER_REVIEW"
}
```

### 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`, `ADDITIONAL_INFO_REQUIRED`, `PROCESSING`, `SUCCESSFUL`, `FAILED`, `REJECTED`. Same values as webhooks.       |
| `statusDetail`        | string (optional) | Present when `status` is `PENDING` and submitted additional information is under review. Value: `ADDITIONAL_INFO_UNDER_REVIEW`. |
| `informationRequests` | array (optional)  | Present when `status` is `ADDITIONAL_INFO_REQUIRED`. Each item describes what compliance has requested. See below.              |
| `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`.             |

### informationRequests

Included when `status` is `ADDITIONAL_INFO_REQUIRED`. Use this to show your users what to provide. Upload supporting documents with [PATCH `/documents`](/api-reference/endpoint/add-documents) when a `FILE` request applies.

| Field             | Type              | Description                                                                                                                              |
| ----------------- | ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `title`           | string            | Short label for the requested item (e.g. "Invoice copy").                                                                                |
| `description`     | string (optional) | Instructions from compliance.                                                                                                            |
| `type`            | string            | Expected input: `TEXT`, `SELECT`, or `FILE`. For API partners, `FILE` requests are usually resolved by uploading via PATCH `/documents`. |
| `section`         | string (optional) | Grouping label when provided.                                                                                                            |
| `options`         | array (optional)  | Allowed values when `type` is `SELECT`.                                                                                                  |
| `rejectionReason` | string (optional) | Present when a previous submission was rejected and must be resubmitted.                                                                 |

## Error Responses

### 404 Not Found

```json theme={null}
{
  "statusCode": 404,
  "message": "Payout not found or not associated with your business",
  "error": "PAYOUT_NOT_FOUND"
}
```

**Solution:** Verify the payout ID and ensure it belongs to your business.

### 401 Unauthorized

```json theme={null}
{
  "statusCode": 401,
  "message": "Unauthorized"
}
```

## Usage Example

```javascript theme={null}
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}`);
```

<Tip>
  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.
</Tip>

## Webhooks

Instead of polling this endpoint, you can subscribe to webhook notifications for real-time status updates:

1. **Activate webhooks** in your Yala dashboard
2. **Configure your webhook endpoint** URL
3. **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.