curl -X GET \
"https://api.khaime.com/api/v1/payouts?status=pending&limit=20" \
-H "X-API-Key: pk_live_your_key"
Marketplace
List Payout Requests
List payout requests awaiting marketplace operator review.
GET
/
payouts
curl -X GET \
"https://api.khaime.com/api/v1/payouts?status=pending&limit=20" \
-H "X-API-Key: pk_live_your_key"
Not available with a partner API key. This endpoint currently requires a logged-in
Khaime dashboard session. Calling it with
X-API-Key returns 404 Route not exist — the
path is correct, but the partner API does not expose it. Use the dashboard for this
operation until it is added to the partner API.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/payouts?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.