curl -X POST https://api.khaime.com/api/v1/marketplace/merchants/1676/payouts \
-H "X-API-Key: pk_sandbox_your_key" \
-H "Content-Type: application/json" \
-d '{
"amount": 50000,
"currency": "NGN",
"description": "Weekly merchant payout"
}'
Marketplace
Initiate Merchant Payout
Request a payout from a sub-merchant’s wallet balance.
POST
/
marketplace
/
merchants
/
{merchantId}
/
payouts
curl -X POST https://api.khaime.com/api/v1/marketplace/merchants/1676/payouts \
-H "X-API-Key: pk_sandbox_your_key" \
-H "Content-Type: application/json" \
-d '{
"amount": 50000,
"currency": "NGN",
"description": "Weekly merchant payout"
}'
Intro
Requests a payout of a sub-merchant’s available balance — the first step in a three-stage approval flow that ends with Khaime settling funds to their bank or Stripe account.Context
This is called with the sub-merchant’s own Partner API key, not the marketplace operator’s — it’s the merchant asking to be paid, not the operator paying them. It only creates a staged request; nothing moves until the marketplace operator calls Approve Merchant Payout (or Reject Merchant Payout to release it back). After operator approval, Khaime’s own admin settlement step is what actually sends money. Before calling this, the merchant needs KYC approved and payout configured (Setup Merchant Payout), and enough available balance — check with Get Merchant Balance.Funds can live in two different places depending on how the merchant gets paid: a Khaime wallet balance (built up from settled charges), or — for merchants on Stripe direct-charge marketplace payments — directly in their Stripe connected account. This endpoint checks whichever source applies and reserves against it.
Hows
Path parameters
string
required
The ID of the sub-merchant whose balance should be paid out.
Request body
number
required
Amount to withdraw, in the smallest currency unit (e.g.
50000 = ₦500.00 for NGN, or $500.00 for USD). Must be a positive whole number — no fractional smallest-unit amounts.string
required
Currency to withdraw, e.g.
NGN, USD, GBP. Must be one of Khaime’s supported collection currencies.string
Optional internal note for the payout request.
Each currency has a minimum payout amount (roughly the local equivalent of $10 — e.g. 500,000 kobo for NGN, 1,000 cents for USD). Requests below the minimum are rejected before anything is reserved.
Response
{
"success": true,
"message": "Sub-merchant payout request submitted. Awaiting marketplace operator approval.",
"data": {
"payout_request_id": 9821,
"merchant_id": 1676,
"amount": 50000,
"currency": "NGN",
"status": "pending",
"remaining_balance": 125000,
"payment_gateway": "gravv",
"payout_method": "transfer",
"bank_details": {
"account_name": "Jordan Ellis",
"account_number": "0123456789",
"bank_name": "Example Bank"
},
"reference": "marketplace_payout_request_1780912800000_1676",
"requested_at": "2026-06-08T10:00:00.000Z"
}
}
payout_method: "payout"), the response instead includes stripe_account_id and withdrawal_source: "stripe_subaccount" in place of bank_details.
Response fields
| Field | Type | Description |
|---|---|---|
merchant_id | number | Sub-merchant business ID |
payout_request_id | number | Staged marketplace payout request ID |
amount | number | Requested amount, smallest currency unit |
currency | string | Currency being withdrawn |
status | string | pending at creation |
remaining_balance | number | Available balance left after reserving this request |
payment_gateway | string | gravv, paystack, flutterwave, startbutton, or stripe_direct — whichever rail settles this merchant |
payout_method | string | transfer (bank/wallet settlement) or payout (Stripe connected-account balance) |
bank_details | object | Destination bank details, present when settlement is a bank transfer |
reference | string | Unique payout reference — used to approve/reject this request |
requested_at | string | ISO timestamp the request was created |
Requirements
- The sub-merchant must have an active marketplace relationship.
- The sub-merchant must have completed KYC and payout setup — for non-NGN/wallet settlement, a connected Stripe account with approved KYC is required.
- The requested amount must clear the per-currency minimum and be a whole number in the smallest unit.
- The currency must be one Khaime supports for collection.
- The sub-merchant must have enough available balance (wallet or Stripe connected-account balance, depending on settlement path) after subtracting anything already reserved by a pending request.
- Only one pending request is allowed per merchant, per currency, per environment (sandbox/live) at a time.
Error cases
| Status | Error | Fix |
|---|---|---|
400 | amount must be a positive number in the smallest currency unit | Send a positive amount |
400 | amount must be a whole number... | Don’t send fractional smallest-unit amounts |
400 | amount must be at least <minimum> <currency>... | Request at least the per-currency minimum |
400 | <currency> payouts are not supported... | Use one of Khaime’s supported collection currencies |
400 | Sub-merchant already has a pending payout request for <currency>... | Approve or reject the existing request first |
400 | Sub-merchant must connect a Stripe account before requesting <currency> payouts | Complete Stripe Connect setup for the merchant |
400 | Sub-merchant Stripe payout verification is pending... | Wait for Stripe KYC to be approved |
400 | Insufficient Stripe balance... / Insufficient sub-merchant wallet balance... | Request a lower amount or wait for more funds to settle |
400 | Sub-merchant bank details are missing. Complete payout setup first. | Complete Setup Merchant Payout for the merchant |
401 | Missing or invalid X-API-Key header | Include a valid Partner API key |
404 | Active marketplace relationship not found for this sub-merchant. | Confirm the merchant is linked and active |
curl -X POST https://api.khaime.com/api/v1/marketplace/merchants/1676/payouts \
-H "X-API-Key: pk_sandbox_your_key" \
-H "Content-Type: application/json" \
-d '{
"amount": 50000,
"currency": "NGN",
"description": "Weekly merchant payout"
}'
Whys
A staged request instead of an immediate withdrawal. Marketplace payouts move real money out of a merchant’s balance, and letting a merchant unilaterally trigger settlement would remove the operator’s ability to catch mistakes, fraud, or disputes before funds leave. Staging the request — reserve now, settle only after two more approvals — buys review time without blocking the merchant from queuing the request the moment they want to. Balance is reserved immediately, before approval. If the reservation waited until the operator approved, a merchant could file several requests for more than their balance covers and race the approval step. Reserving on request keepsremaining_balance accurate and prevents overcommitment.
Different settlement paths for wallet vs. Stripe-direct-charge merchants. Not every merchant’s funds land in the same place — it depends on how their charges were processed. Rather than forcing every payout through one channel, the endpoint detects where the merchant’s money actually is and reserves against that source.
Why nots
- Doesn’t move money. This only stages a request — it takes an Approve Merchant Payout from the marketplace operator, and settlement from Khaime admin, before funds actually go anywhere.
- Not a substitute for checking balance first. Call Get Merchant Balance before requesting — this endpoint validates balance server-side, but you’ll get a cleaner UX by not letting a merchant submit a request you already know will fail.
- No partial payouts or queued requests. You can’t have more than one pending request per merchant/currency/environment — a second request while one is pending is rejected outright rather than queued.
- Doesn’t let a merchant choose the settlement rail. Which gateway handles the payout (
gravv,paystack,stripe_direct, etc.) is determined by the merchant’s currency and existing payout configuration, not a parameter you can set on the request.