Skip to main content
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-id-key: your_dashboard_auth_token" \
  -H "X-Environment: live"

​
Approve Merchant Payout

Approve a staged request created by a sub-merchant with Initiate Merchant Payout. Approval creates the final wallet withdrawal for Khaime admin review. This dashboard endpoint uses x-id-key authentication, not a Partner API key.
This endpoint does not accept a request body. The marketplace operator cannot change the amount, currency, payout method, or payment gateway during approval. It does not contact the payment gateway.
Approval changes the request from pending to approved and creates a payout_pending wallet transaction. Khaime admin must approve that withdrawal before gateway processing begins.

​
Path Parameters

​
merchantId
number
required
The business ID of the sub-merchant whose payout should be approved.
​
reference
string
required
The payout reference returned by the initiate payout endpoint.

​
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"
  }
}
Use the returned reference with Khaime’s existing admin withdrawal settlement flow. Until then, the wallet transaction remains payout_pending.

​
Response Fields

FieldTypeDescription
payout_request_idnumberStaged marketplace request ID
withdrawal_idnumberWallet transaction ID for the payout
merchant_idnumberSub-merchant business ID
referencestringUnique payout reference
amountnumberPayout amount in the smallest currency unit
currencystringPayout currency
request_statusstringMarketplace request status, approved
withdrawal_statusstringFinal withdrawal status, payout_pending
payment_gatewaystringGateway selected when the payout was initiated
payout_methodstringSettlement method stored on the payout
approved_atstringISO timestamp of operator approval

​
Requirements

  • The API key must belong to the marketplace operator associated with the requesting merchant.
  • The merchantId must have an active relationship with the marketplace.
  • The payout must have been created through the marketplace Partner API.
  • The API key environment must match the payout environment.
  • The staged request must currently have status pending.

​
Error Codes

StatusErrorMeaning
400Approval failedThe request could not be validated or started
401UnauthorizedThe Partner API key is missing or invalid
403Permission deniedThe payout belongs to another marketplace
404Payout request not foundThe merchant relationship, environment, or reference does not match
409Already claimedThe payout is no longer pending or another approval claimed it
curl -X POST \
  "https://api.khaime.com/api/v1/marketplace/merchants/1676/payouts/marketplace_payout_request_1780912800000_1676/approve" \
  -H "x-id-key: your_dashboard_auth_token" \
  -H "X-Environment: live"