Get Merchant Balance

​

Intro

​

Context

​

Hows

​

Path parameters

​

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

​

Balance calculation

balance = total_credits - total_debits

​

Currency units

​

Error cases

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

​

Whys

​

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: 1250000 and a pending payout request for 1000000 doesn’t have 1250000 genuinely 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.