curl -X POST \
"https://api.khaime.com/api/v1/marketplace/merchants/1676/payouts/marketplace_payout_request_1780912800000_1676/reject" \
-H "X-API-Key: pk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"reason":"Payout requires additional merchant verification."}'
Marketplace
Reject Merchant Payout
Reject a pending payout request and release its reserved balance.
POST
/
marketplace
/
merchants
/
{merchantId}
/
payouts
/
{reference}
/
reject
curl -X POST \
"https://api.khaime.com/api/v1/marketplace/merchants/1676/payouts/marketplace_payout_request_1780912800000_1676/reject" \
-H "X-API-Key: pk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"reason":"Payout requires additional merchant verification."}'
Intro
Rejects a staged payout request before it becomes a real withdrawal, and releases the balance that was reserved for it back to the merchant.Context
This is the other branch of the operator’s checkpoint alongside Approve Merchant Payout — every request a merchant creates via Initiate Merchant Payout ends up either approved or rejected before it can reach Khaime’s settlement step. Call it with your marketplace operator Partner API key.Hows
Path parameters
number
required
The business ID of the requesting sub-merchant.
string
required
The reference returned when the sub-merchant created the request.
Request body
string
required
A reason between 3 and 500 characters. This is stored on the request and can be surfaced to the merchant.
Response
{
"success": true,
"message": "Sub-merchant payout request rejected. Reserved funds have been released.",
"data": {
"payout_request_id": 9821,
"merchant_id": 1676,
"reference": "marketplace_payout_request_1780912800000_1676",
"status": "rejected",
"rejection_reason": "Payout requires additional merchant verification.",
"rejected_at": "2026-06-08T10:15:00.000Z"
}
}
Error cases
| Status | Error | Fix |
|---|---|---|
400 | reason missing, too short, or too long | Send a reason between 3 and 500 characters |
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 rejected from status "<status>". | The request is no longer pending — already approved or rejected |
curl -X POST \
"https://api.khaime.com/api/v1/marketplace/merchants/1676/payouts/marketplace_payout_request_1780912800000_1676/reject" \
-H "X-API-Key: pk_live_your_key" \
-H "Content-Type: application/json" \
-d '{"reason":"Payout requires additional merchant verification."}'
Whys
A required, minimum-length reason. A rejection blocks a merchant from getting paid, at least until they try again — requiring a substantive reason (not an empty string or a one-character placeholder) keeps a paper trail for the merchant and for Khaime, and discourages silent, unexplained rejections. Rejection releases the reservation immediately. The balance reserved at request time isn’t useful to anyone sitting in limbo — releasing it as soon as the operator rejects means the merchant can correct whatever the problem was and try again right away, rather than waiting on a separate cleanup step.Why nots
- Doesn’t undo an approval. Once a request has moved to
approved, rejecting it isn’t possible — this endpoint only works on requests still inpending. - Not a way to edit a request. There’s no “reject with a correction” — the merchant has to submit a brand-new Initiate Merchant Payout request after a rejection.
- Doesn’t notify the merchant on your behalf. The rejection reason is stored on the request; surfacing it to the merchant (email, in-app notice, etc.) is on your platform to handle.