curl -X POST \
"https://api.khaime.com/api/v1/marketplace/merchants/1676/payouts/marketplace_payout_request_1780912800000_1676/approve" \
-H "X-API-Key: pk_live_your_key"
Marketplace
Approve Merchant Payout
Approve a staged sub-merchant payout request.
POST
/
marketplace
/
merchants
/
{merchantId}
/
payouts
/
{reference}
/
approve
curl -X POST \
"https://api.khaime.com/api/v1/marketplace/merchants/1676/payouts/marketplace_payout_request_1780912800000_1676/approve" \
-H "X-API-Key: pk_live_your_key"
Intro
Approves a staged payout request a sub-merchant created with Initiate Merchant Payout, moving it from a marketplace-level request to a real wallet withdrawal queued for Khaime’s own settlement review.Context
This is the marketplace operator’s checkpoint in the payout flow:initiate (merchant) → approve (you) → reject (you, alternatively) → Khaime admin settlement. Call it with your marketplace operator Partner API key — the key’s environment (sandbox or live) determines which payout requests you can see and approve. Use List Payout Requests to find pending requests and their reference values first.
Hows
Path parameters
number
required
The business ID of the sub-merchant whose payout should be approved.
string
required
The payout reference returned by Initiate Merchant Payout.
No request body. You can’t change the amount, currency, payout method, or gateway during approval — those were fixed when the merchant initiated the request. Approving also doesn’t contact the payment gateway; that happens at Khaime’s settlement step.
Response
{
"success": true,
"message": "Sub-merchant payout approved. Awaiting Khaime admin settlement.",
"data": {
"payout_request_id": 9821,
"withdrawal_id": 1104,
"merchant_id": 1676,
"reference": "marketplace_payout_request_1780912800000_1676",
"amount": 50000,
"currency": "NGN",
"request_status": "approved",
"withdrawal_status": "payout_pending",
"payment_gateway": "gravv",
"payout_method": "transfer",
"approved_at": "2026-06-08T10:00:00.000Z"
}
}
| Field | Type | Description |
|---|---|---|
payout_request_id | number | Staged marketplace request ID |
withdrawal_id | number | Wallet transaction ID created for the payout |
merchant_id | number | Sub-merchant business ID |
reference | string | Unique payout reference |
amount | number | Payout amount, smallest currency unit |
currency | string | Payout currency |
request_status | string | Marketplace request status — approved |
withdrawal_status | string | Wallet withdrawal status — payout_pending |
payment_gateway | string | Gateway selected when the payout was initiated |
payout_method | string | Settlement method — transfer or payout |
approved_at | string | ISO timestamp of your approval |
payout_pending wallet withdrawal; the reference stays useful afterward for tracking through Khaime’s admin settlement.
Requirements
- Your API key must belong to the marketplace operator associated with the merchant.
- The merchant must have an active relationship with your marketplace.
- The request must have been created through the marketplace Partner API.
- The API key’s environment must match the request’s environment (sandbox/live).
- The request must currently be
pending— the first approval wins if two calls race. - Enough balance must still be available at approval time — a merchant’s balance can shrink between requesting and approval (e.g. a refund lands), so this is re-checked, not assumed from the initial request.
Error cases
| Status | Error | Fix |
|---|---|---|
400 | Payout request amount is invalid. | Underlying data issue on the request — contact support |
400 | Insufficient available balance. Available: X, Requested: Y | The merchant’s balance has since dropped below the requested amount |
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 |
403 | This payout request does not belong to the authenticated marketplace. | The reference belongs to a different marketplace |
404 | Active merchant relationship not found | The merchant is not linked to your marketplace |
404 | Marketplace payout request not found. | The merchant, environment, or reference don’t match an existing request |
409 | This payout request cannot be approved from status "<status>". | The request is no longer pending — already approved, rejected, or claimed by a concurrent call |
curl -X POST \
"https://api.khaime.com/api/v1/marketplace/merchants/1676/payouts/marketplace_payout_request_1780912800000_1676/approve" \
-H "X-API-Key: pk_live_your_key"
Whys
Approval creates a withdrawal but doesn’t settle it. Marketplace operators can vouch that a payout is legitimate, but final settlement — the step that actually moves money through a payment gateway — stays under Khaime’s own review. This two-tier approval (operator, then Khaime admin) keeps marketplace operators able to manage their own merchants’ payouts without giving any single operator direct control over gateway-level fund movement. Balance is re-checked at approval, not just at request time. Time passes between a merchant requesting a payout and an operator approving it — refunds, chargebacks, or other debits can land in between. Re-validating balance at approval prevents approving a payout the merchant can no longer actually cover. No request body on approval. Letting an operator change the amount or destination at approval time would mean the merchant never actually agreed to what gets paid out — the terms are locked in at initiation, and approval is strictly a yes/no gate.Why nots
- Doesn’t settle funds. Approval only gets the request in front of Khaime’s own admin settlement — don’t treat “approved” as “paid.”
- Can’t be partially approved. It’s the full requested amount or nothing; there’s no mechanism to approve a lower amount than requested.
- Not reversible by re-calling this endpoint. Once a request is
approved, calling approve again on the same reference fails with a conflict — use your own internal process (and Khaime support, if needed) to handle a mistaken approval.