Skip to main content
GET
/
marketplace
/
merchants
/
{merchantId}
/
balance
curl -X GET https://api.khaime.com/api/v1/partner/marketplace/merchants/1676/balance \
  -H "X-API-Key: pk_sandbox_your_key"

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.

​
Get Merchant Balance

Retrieve the wallet balances for a specific sub-merchant in your marketplace. Returns balances for all currencies the merchant has received payments in.

​
Path Parameters

​
merchantId
string
required
The ID of the sub-merchant to retrieve balances for.

​
Response

{
  "success": true,
  "message": "Merchant balance retrieved successfully",
  "data": {
    "merchant_id": 1676,
    "balances": [
      {
        "currency": "NGN",
        "balance": 1250000,
        "formatted_balance": "NGN 12500.00",
        "total_credits": 1500000,
        "total_debits": 250000,
        "transaction_count": 45
      },
      {
        "currency": "USD",
        "balance": 85000,
        "formatted_balance": "USD 850.00",
        "total_credits": 100000,
        "total_debits": 15000,
        "transaction_count": 12
      }
    ]
  }
}

​
Response Fields

​
balances (array)

FieldTypeDescription
currencystringCurrency code (e.g., NGN, USD, GBP)
balancenumberCurrent balance in smallest currency unit (cents/kobo)
formatted_balancestringHuman-readable balance with currency symbol
total_creditsnumberTotal credits received in smallest unit
total_debitsnumberTotal debits (payouts/refunds) in smallest unit
transaction_countnumberTotal number of wallet transactions

​
Balance Calculation

The balance is calculated as: 
balance = total_credits - total_debits
Credits include:
  • Successful payment settlements from charges
Debits include:
  • Payouts to bank accounts
  • Refunds issued

​
Currency Units

All amounts are returned in the smallest currency unit:
CurrencyUnitExample
USD, GBP, EURcents85000 = $850.00
NGNkobo1250000 = 12,500.00
JPY, KRW, VNDwhole units1000 = 1,000

​
Error Codes

StatusErrorFix
403This endpoint is restricted to marketplace operatorsYour account must have marketplace mode enabled
404Active merchant relationship not foundThe merchant is not actively linked to your marketplace
curl -X GET https://api.khaime.com/api/v1/partner/marketplace/merchants/1676/balance \
  -H "X-API-Key: pk_sandbox_your_key"