> ## Documentation Index
> Fetch the complete documentation index at: https://docs.khaime.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Payout Requests

> List payout requests awaiting marketplace operator review.

# List Payout Requests

Retrieve staged payout requests belonging to the authenticated marketplace. Marketplace operators use the returned `reference` and `merchant_id` to approve a request.

Authenticate with your marketplace operator Partner API key via the `X-API-Key` header. The key's environment (sandbox or live) determines which payout requests are returned.

## Query Parameters

<ParamField query="status" type="string" default="pending">
  Filter by `pending`, `approved`, `rejected`, or `cancelled`.
</ParamField>

<ParamField query="merchant_id" type="number">
  Optionally return requests for one sub-merchant.
</ParamField>

<ParamField query="page" type="number" default="1">
  Page number.
</ParamField>

<ParamField query="limit" type="number" default="20">
  Results per page. Maximum `100`.
</ParamField>

## Response

```json theme={null}
{
  "success": true,
  "message": "Marketplace payout requests retrieved successfully.",
  "data": {
    "requests": [
      {
        "id": 9821,
        "reference": "marketplace_payout_request_1780912800000_1676",
        "merchant_id": 1676,
        "amount": "50000",
        "currency": "NGN",
        "status": "pending",
        "payment_gateway": "gravv",
        "payout_method": "transfer",
        "is_live": true,
        "wallet_transaction_id": null,
        "requested_at": "2026-06-08T10:00:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 1,
      "pages": 1
    }
  }
}
```

<Note>
  Sandbox and live requests are isolated. The environment of the Partner API key
  determines which records are returned.
</Note>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET \
    "https://api.khaime.com/api/v1/partner/marketplace/payout-requests?status=pending&limit=20" \
    -H "X-API-Key: pk_live_your_key"
  ```
</RequestExample>

## Related

* [Approve Merchant Payout](/api-reference/marketplace/approve-payout)
* [Reject Merchant Payout](/api-reference/marketplace/reject-payout)
* [Initiate Merchant Payout](/api-reference/marketplace/initiate-payout)