curl -X GET https://api.khaime.com/api/v1/partner/marketplace/merchants/1676/balance \
  -H "X-API-Key: pk_sandbox_your_key"

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"

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)

Field	Type	Description
`currency`	string	Currency code (e.g., `NGN`, `USD`, `GBP`)
`balance`	number	Current balance in smallest currency unit (cents/kobo)
`formatted_balance`	string	Human-readable balance with currency symbol
`total_credits`	number	Total credits received in smallest unit
`total_debits`	number	Total debits (payouts/refunds) in smallest unit
`transaction_count`	number	Total 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:

Currency	Unit	Example
USD, GBP, EUR	cents	85000 = $850.00
NGN	kobo	1250000 = 12,500.00
JPY, KRW, VND	whole units	1000 = 1,000

Error Codes

Status	Error	Fix
`403`	`This endpoint is restricted to marketplace operators`	Your account must have marketplace mode enabled
`404`	`Active merchant relationship not found`	The 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"

Resubmit Merchant KYC Get Supported Payout Banks

API Reference

Account

Products & Pricing

Payments

Subscriptions

Marketplace

B2B Commerce

Get Merchant Balance

Get Merchant Balance

Path Parameters

Response

Response Fields

balances (array)

Balance Calculation

Currency Units

Error Codes

​Get Merchant Balance

​Path Parameters

​Response

​Response Fields

​balances (array)

​Balance Calculation

​Currency Units

​Error Codes

Get Merchant Balance

Path Parameters

Response

Response Fields

balances (array)

Balance Calculation

Currency Units

Error Codes