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"

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

Field	Type	Description
`payout_request_id`	number	Staged marketplace request ID
`withdrawal_id`	number	Wallet transaction ID for the payout
`merchant_id`	number	Sub-merchant business ID
`reference`	string	Unique payout reference
`amount`	number	Payout amount in the smallest currency unit
`currency`	string	Payout currency
`request_status`	string	Marketplace request status, `approved`
`withdrawal_status`	string	Final withdrawal status, `payout_pending`
`payment_gateway`	string	Gateway selected when the payout was initiated
`payout_method`	string	Settlement method stored on the payout
`approved_at`	string	ISO 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

Status	Error	Meaning
`400`	Approval failed	The request could not be validated or started
`401`	Unauthorized	The Partner API key is missing or invalid
`403`	Permission denied	The payout belongs to another marketplace
`404`	Payout request not found	The merchant relationship, environment, or reference does not match
`409`	Already claimed	The 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"

List Payout Requests Reject Merchant Payout

API Reference

Account

Products & Pricing

Payments

Subscriptions

Marketplace

B2B Commerce

Approve Merchant Payout

Approve Merchant Payout

Path Parameters

Response

Response Fields

Requirements

Error Codes

​Approve Merchant Payout

​Path Parameters

​Response

​Response Fields

​Requirements

​Error Codes

​Related

Approve Merchant Payout

Path Parameters

Response

Response Fields

Requirements

Error Codes

Related