Initiate Merchant Payout

Request a payout from a sub-merchant’s available balance. This endpoint must be called using the sub-merchant’s own Partner API key after KYC and payout setup are complete.

This payout is created from the sub-merchant’s Khaime wallet balance. For Stripe direct-charge marketplace payments, funds may already be held in the sub-merchant’s Stripe connected account instead of their Khaime wallet.

This endpoint creates a staged request with status pending; it does not create the final wallet withdrawal. The marketplace operator must call Approve Merchant Payout, after which Khaime admin performs the final settlement approval.

Path Parameters

string

required

The ID of the sub-merchant whose wallet should be paid out.

Request Body

number

required

Amount to withdraw in the smallest currency unit. For example, 50000 means ₦500.00 for NGN or $500.00 for USD.

string

required

Wallet currency to withdraw, such as NGN, USD, or GBP.

string

Optional internal description for the payout request.

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"
  }
}

Response Fields

Field	Type	Description
`merchant_id`	number	Sub-merchant business ID
`payout_request_id`	number	Staged marketplace payout request ID
`amount`	number	Requested payout amount in the smallest currency unit
`currency`	string	Currency being withdrawn
`status`	string	Request status, `pending` at creation
`remaining_balance`	number	Available balance after reserving this request
`payment_gateway`	string	Gateway selected for settlement
`reference`	string	Unique payout reference
`payout_method`	string	`transfer` for wallet settlement or `payout` for Stripe direct-charge funds
`bank_details`	object	Destination bank details when the gateway uses a bank transfer
`requested_at`	string	ISO timestamp when the request was created

Requirements

Your API key must belong to the sub-merchant identified by merchantId.
The sub-merchant must have an active marketplace relationship.
The sub-merchant must have completed KYC and payout setup.
The sub-merchant must have enough available wallet balance in the requested currency.
Only one pending request is allowed per merchant, currency, and environment.
The requested amount is reserved while marketplace approval is pending.

Error Codes

Status	Error	Fix
`400`	`Insufficient wallet balance`	Request a lower amount or wait for more funds to settle
`409`	`Sub-merchant already has a payout awaiting marketplace approval`	Approve or reject the existing request first
`400`	`Please store bank account details first before requesting payouts`	Complete payout setup for the merchant
`403`	`A sub-merchant can only request a payout for its own business`	Use the sub-merchant’s own Partner API key
`404`	`Active merchant relationship not found`	Confirm the merchant is linked and active

curl -X POST https://api.khaime.com/api/v1/partner/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"
  }'

API Reference

Account

Products & Pricing

Payments

Subscriptions

Marketplace

Initiate Merchant Payout

Initiate Merchant Payout

Path Parameters

Request Body

Response

Response Fields

Requirements

Error Codes

​Initiate Merchant Payout

​Path Parameters

​Request Body

​Response

​Response Fields

​Requirements

​Error Codes

​Related

Initiate Merchant Payout

Path Parameters

Request Body

Response

Response Fields

Requirements

Error Codes

Related