curl -X GET \
"https://api.khaime.com/api/v1/marketplace/payout-requests?status=pending&limit=20" \
-H "X-API-Key: pk_live_your_key"
Marketplace
List Payout Requests
List payout requests awaiting marketplace operator review.
GET
/
marketplace
/
payout-requests
curl -X GET \
"https://api.khaime.com/api/v1/marketplace/payout-requests?status=pending&limit=20" \
-H "X-API-Key: pk_live_your_key"
Intro
Lists staged payout requests belonging to your marketplace, so you can find the ones awaiting your decision and pull thereference and merchant_id needed to approve or reject them.
Context
This is the discovery step ahead of Approve Merchant Payout and Reject Merchant Payout — rather than merchants notifying you out-of-band that a payout request exists, poll this endpoint (or build a dashboard on top of it) to see what’s pending. Requests originate from merchants calling Initiate Merchant Payout.Hows
Query parameters
string
default:"pending"
Filter by
pending, approved, rejected, or cancelled.number
Restrict results to one sub-merchant.
number
default:"1"
Page number.
number
default:"20"
Results per page. Maximum
100.Response
{
"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",
"description": "Weekly merchant payout",
"is_live": true,
"wallet_transaction_id": null,
"requested_at": "2026-06-08T10:00:00.000Z",
"approved_at": null,
"rejected_at": null,
"cancelled_at": null
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 1,
"pages": 1
}
}
}
Response fields
| Field | Type | Description |
|---|---|---|
id | number | Payout request ID |
reference | string | Unique reference — pass to Approve or Reject |
merchant_id | number | Sub-merchant business ID |
amount | string | Requested amount, smallest currency unit |
currency | string | Payout currency |
status | string | pending, approved, rejected, or cancelled |
payment_gateway | string | Rail this payout settles on |
payout_method | string | transfer or payout |
description | string | null | Optional note set at initiation |
is_live | boolean | Whether this is a live or sandbox request |
wallet_transaction_id | number | null | Set once approved and a withdrawal exists |
requested_at / approved_at / rejected_at / cancelled_at | string | null | Lifecycle timestamps — only the relevant one(s) are populated |
Sandbox and live requests are isolated. The environment of your Partner API key determines which records this returns — a sandbox key never sees live requests and vice versa.
Error cases
| Status | Error | Fix |
|---|---|---|
400 | Invalid status, page, or limit value | status must be one of the four allowed values; page/limit must be positive integers, limit ≤ 100 |
401 | Missing or invalid X-API-Key header | Include a valid Partner API key |
403 | This endpoint is restricted to marketplace operators | Your API key must belong to a marketplace operator account |
curl -X GET \
"https://api.khaime.com/api/v1/marketplace/payout-requests?status=pending&limit=20" \
-H "X-API-Key: pk_live_your_key"
Whys
Defaults tostatus=pending. The most common reason to call this endpoint is “what needs my attention right now” — defaulting to pending requests means a simple, no-query-params call already answers that, rather than returning a full unfiltered history you’d have to filter client-side.
Pagination capped at 100. A hard ceiling on limit keeps a single request bounded and predictable regardless of how large a marketplace’s request history grows, rather than letting an unbounded query degrade as volume increases.
Why nots
- Not real-time. This is a snapshot at request time — for a live “new request” notification, you’d need to poll or build your own event on top of it; there’s no webhook covering payout-request creation documented here.
- Doesn’t expose other marketplaces’ requests. Results are always scoped to your own marketplace and API key environment — there’s no cross-marketplace visibility, by design.
- Not a transaction ledger. This tracks the marketplace-level request lifecycle (pending → approved/rejected), not the underlying wallet withdrawal’s settlement status with the payment gateway — for that, use
wallet_transaction_idtogether with your own reconciliation process once a request is approved.