curl -X GET https://api.khaime.com/api/v1/merchants/1676/balance \
-H "X-API-Key: pk_sandbox_your_key"
Marketplace
Get Merchant Balance
Retrieve wallet balances for a sub-merchant across all currencies.
GET
/
merchants
/
{merchantId}
/
balance
curl -X GET https://api.khaime.com/api/v1/merchants/1676/balance \
-H "X-API-Key: pk_sandbox_your_key"
Intro
Returns a sub-merchant’s Khaime wallet balances, broken out by currency — the number to check before requesting or approving a payout.Context
This reads the wallet side of the payout flow: it’s what a merchant (or the operator, on their behalf) should check before calling Initiate Merchant Payout, and what an operator can use to sanity-check a request before calling Approve Merchant Payout. Balances build up from settled charges made against the merchant and go down from payouts and refunds.Hows
Path parameters
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
}
]
}
}
balances array rather than an error.
The numbers are scoped to the API key’s mode. A sandbox key reports sandbox money only, a live key reports live money only — the same figure Initiate Merchant Payout checks against. A merchant who has taken both test and real payments has two separate balances, and neither total includes the other.
Response fields
| Field | Type | Description |
|---|---|---|
currency | string | Currency code (e.g., NGN, USD, GBP) |
balance | number | Current balance, smallest currency unit |
formatted_balance | string | Human-readable balance with currency code |
total_credits | number | Total credits ever received, smallest unit |
total_debits | number | Total debits (payouts, refunds) ever recorded, smallest unit |
transaction_count | number | Total wallet transactions behind this balance |
Balance calculation
balance = total_credits - total_debits
balance does not subtract funds already reserved by a pending payout request — check List Payout Requests if you need to account for in-flight reservations, since Initiate Merchant Payout itself calculates and enforces that separately.
Currency units
All amounts are in the smallest currency unit:| Currency | Unit | Example |
|---|---|---|
| USD, GBP, EUR, NGN | cents / kobo | 85000 = $850.00; 1250000 = ₦12,500.00 |
| JPY, KRW, VND | whole units | 1000 = 1,000 |
Error cases
| Status | Error | Fix |
|---|---|---|
401 | Missing or invalid X-API-Key header | Include a valid Partner API key |
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/merchants/1676/balance \
-H "X-API-Key: pk_sandbox_your_key"
Whys
Broken out by currency instead of one combined number. A merchant selling in multiple currencies has genuinely separate, non-fungible balances — there’s no meaningful single “total” across NGN and USD without an exchange rate assumption Khaime isn’t going to make on your behalf. Returning an array keeps each currency’s numbers exact. One environment at a time. Test money and real money are different money. Reporting them as one number would let a sandbox payout pass a balance check on real funds, so each mode is summed on its own and the key you call with decides which you see. Both raw and formatted balance.balance (smallest unit, integer) is what you should use for any arithmetic or comparison against amounts sent to other endpoints like Initiate Merchant Payout; formatted_balance exists purely so you’re not writing your own smallest-unit-to-major-unit formatting logic for a quick display.
Why nots
- Not a live ledger view. This reflects settled wallet transactions — it doesn’t show pending/in-flight charges still working their way through a payment gateway.
- Doesn’t account for pending payout reservations. A merchant with
balance: 1250000and a pending payout request for1000000doesn’t have1250000genuinely available — the reservation isn’t subtracted here. Cross-reference List Payout Requests if you need the true available amount ahead of calling Initiate Merchant Payout (which enforces the reservation itself). - Doesn’t cover Stripe connected-account balances. For merchants settling via Stripe direct-charge marketplace payments, funds can sit in their Stripe connected account rather than a Khaime wallet — this endpoint only reports the Khaime wallet side.
- Not a transaction history endpoint. You get aggregate totals and a count, not the underlying list of transactions — that’s a separate concern outside this endpoint’s scope.