Skip to Content
API ReferenceWallet & Balance

Wallet & Balance API

Check wallet balances across different currencies.

Test Environment Balances: Test account balances vary by account. New accounts may start with zero balance. Contact the admin team to request a balance top-up for testing.

Get Balance

Retrieve wallet balance for a specific currency or all currencies.

GET /business/balance

Query Parameters

ParameterTypeRequiredDescription
currencystringNoCurrency code (USD, KES, TZS, UGX, ZAR). If omitted, returns all balances

Example Requests

Single Currency

curl https://api.test.wakapay.io/business/balance?currency=USD \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
const response = await fetch(
  "https://api.test.wakapay.io/business/balance?currency=USD",
  {
    headers: {
      Authorization: "Bearer YOUR_ACCESS_TOKEN",
    },
  },
);
 
const balance = await response.json();
console.log(balance);
import requests
 
response = requests.get(
    'https://api.test.wakapay.io/business/balance',
    params={'currency': 'USD'},
    headers={'Authorization': 'Bearer YOUR_ACCESS_TOKEN'}
)
 
balance = response.json()
print(balance)

All Currencies

curl https://api.test.wakapay.io/business/balance \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

Success Response - Single Currency

Status Code: 200 OK

{
  "available": 5000000,
  "businessId": "019d****-****-****-****-********19c3",
  "currency": "USD",
  "holding": 0,
  "pending": 0
}

Success Response - All Currencies

Status Code: 200 OK

{
  "businessId": "019d****-****-****-****-********19c3",
  "items": [
    {
      "available": 5000000,
      "currency": "USD",
      "holding": 0,
      "pending": 0
    },
    {
      "available": 0,
      "currency": "KES",
      "holding": 0,
      "pending": 0
    },
    {
      "available": 0,
      "currency": "TZS",
      "holding": 0,
      "pending": 0
    }
  ]
}

Response Fields

FieldTypeDescription
availablenumberAvailable balance that can be used for payouts
businessIdstringYour business ID
currencystringCurrency code (USD, KES, TZS, UGX, ZAR)
holdingnumberFunds on hold (reserved for processing transactions)
pendingnumberPending funds (transactions in progress)
itemsarrayArray of balance objects (when querying all currencies)

Balance States

Available Balance

Funds that can be immediately used for payouts. This is the balance you should check before initiating a payout.

Holding Balance

Funds temporarily reserved for:

  • Transactions in processing
  • Pending payouts
  • Risk management holds

These funds will be released back to available or moved to pending once the transaction completes.

Pending Balance

Funds from:

  • Incoming transfers
  • Refunds being processed
  • Collections being settled

These funds will become available once fully processed.

Error Responses

401 - Missing Authorization

Missing Authorization header:

{
  "message": "missing value in request header"
}

401 - Invalid Token

Malformed or invalid JWT token:

{
  "message": "token is malformed: token contains an invalid number of segments"
}

Invalid Currency Code

If you query an invalid or unsupported currency, the API returns a zero balance instead of an error:

{
  "available": 0,
  "businessId": "019d****-****-****-****-********19c3",
  "currency": "INVALID",
  "holding": 0,
  "pending": 0
}

Supported Currencies

CurrencyCodeCountries
US DollarUSDCross-border transactions
Kenyan ShillingKESKenya
Tanzanian ShillingTZSTanzania
Ugandan ShillingUGXUganda
South African RandZARSouth Africa

Usage Examples

Check Before Payout

Always check available balance before initiating a payout:

async function sendPayout(amount, currency) {
  // Check balance first
  const balanceResponse = await fetch(
    `https://api.test.wakapay.io/business/balance?currency=${currency}`,
    {
      headers: { Authorization: `Bearer ${token}` },
    },
  );
 
  const balance = await balanceResponse.json();
 
  if (balance.available < amount) {
    throw new Error("Insufficient balance");
  }
 
  // Proceed with payout
  // ...
}

Monitor All Wallets

async function getAllBalances() {
  const response = await fetch("https://api.test.wakapay.io/business/balance", {
    headers: { Authorization: `Bearer ${token}` },
  });
 
  const data = await response.json();
 
  // Display all balances
  data.items.forEach((wallet) => {
    console.log(`${wallet.currency}: ${wallet.available} available`);
  });
 
  return data.items;
}

Best Practices

  • Check before payout: Always verify sufficient balance before initiating payouts
  • Monitor holding: High holding balance may indicate pending transactions
  • Currency match: Ensure you check the correct currency for your payout
  • Webhook integration: Set up webhooks to track balance changes in real-time
  • Alert thresholds: Set up alerts when balance falls below a threshold
Last updated on
AuthenticationFX Rates