Skip to main content
POST
/
marketplace
/
merchants
/
{merchantId}
/
payouts
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"
  }'

Documentation Index

Fetch the complete documentation index at: https://docs.khaime.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Initiate Merchant Payout

Request a payout from a sub-merchant’s wallet balance. This endpoint lets a marketplace operator initiate a withdrawal for a linked sub-merchant after the merchant has completed KYC and payout setup.
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.
Payout requests are submitted for processing and may require review before funds are sent. The response status is usually payout_pending.

​
Path Parameters

​
merchantId
string
required
The ID of the sub-merchant whose wallet should be paid out.

​
Request Body

​
amount
number
required
Amount to withdraw in the smallest currency unit. For example, 50000 means ₦500.00 for NGN or $500.00 for USD.
​
currency
string
required
Wallet currency to withdraw, such as NGN, USD, or GBP.
​
description
string
Optional internal description for the payout request.

​
Response

{
  "success": true,
  "message": "Payout request submitted successfully. Awaiting processing.",
  "data": {
    "merchant_id": 1676,
    "withdrawal_id": 9821,
    "amount": 50000,
    "currency": "NGN",
    "status": "payout_pending",
    "reference": "marketplace_payout_1764300000000_1042_1676",
    "payout_method": "transfer",
    "initiated_by_marketplace_id": 1042,
    "created_at": "2026-05-28T12:00:00.000Z"
  }
}

​
Response Fields

FieldTypeDescription
merchant_idnumberSub-merchant business ID
withdrawal_idnumberWallet transaction ID for the payout debit
amountnumberRequested payout amount in the smallest currency unit
currencystringCurrency being withdrawn
statusstringPayout status, usually payout_pending at creation
referencestringUnique payout reference
payout_methodstringtransfer for wallet-based payout processing
initiated_by_marketplace_idnumberMarketplace operator business ID
created_atstringISO timestamp when the request was created

​
Requirements

  • Your API key must belong to a marketplace operator.
  • The merchantId must be an active sub-merchant in your marketplace.
  • 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 payout is allowed per merchant and currency at a time.

​
Error Codes

StatusErrorFix
400Insufficient wallet balanceRequest a lower amount or wait for more funds to settle
400You already have a pending payout request for this currencyWait for the existing payout to complete
400Please store bank account details first before requesting payoutsComplete payout setup for the merchant
403This endpoint is restricted to marketplace operatorsUse an API key from a marketplace operator account
404Active merchant relationship not foundConfirm 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"
  }'