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

​
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

​
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": "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

FieldTypeDescription
merchant_idnumberSub-merchant business ID
payout_request_idnumberStaged marketplace payout request ID
amountnumberRequested payout amount in the smallest currency unit
currencystringCurrency being withdrawn
statusstringRequest status, pending at creation
remaining_balancenumberAvailable balance after reserving this request
payment_gatewaystringGateway selected for settlement
referencestringUnique payout reference
payout_methodstringtransfer for wallet settlement or payout for Stripe direct-charge funds
bank_detailsobjectDestination bank details when the gateway uses a bank transfer
requested_atstringISO 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

StatusErrorFix
400Insufficient wallet balanceRequest a lower amount or wait for more funds to settle
409Sub-merchant already has a payout awaiting marketplace approvalApprove or reject the existing request first
400Please store bank account details first before requesting payoutsComplete payout setup for the merchant
403A sub-merchant can only request a payout for its own businessUse the sub-merchant’s own Partner API key
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"
  }'