Skip to main content
GET
/
api
/
v1
/
payments
/
wallet
/
balance
Wallet Balance
curl --request GET \
  --url https://api.example.com/api/v1/payments/wallet/balance
{
  "wallet_balance": {
    "balance": "<string>",
    "currency": "<string>"
  }
}

Overview

Retrieve the current balance in your Africa’s Talking wallet. This is useful for monitoring available funds before initiating payments and for financial reporting.

Request

No request body or parameters required.

Response

wallet_balance
object
Wallet balance information from Africa’s Talking

Example Request

curl http://localhost:8000/api/v1/payments/wallet/balance

Example Response

{
  "wallet_balance": {
    "balance": "KES 5,432.10",
    "currency": "KES"
  }
}

Error Response

{
  "detail": "Failed to get wallet balance"
}

Status Codes

  • 200 - Balance retrieved successfully
  • 500 - Failed to query wallet balance

Use Cases

Check if sufficient balance exists before initiating a large payment or bulk payment operation.
Track wallet balance over time to monitor payment activity and plan top-ups.
Integrate with monitoring systems to alert when balance falls below a threshold.
Verify wallet balance matches expected values based on payment history.

Implementation

This endpoint calls the Africa’s Talking Payments API to retrieve the current wallet balance. It requires valid production credentials (sandbox wallets show test balance). Source: payments.py:230-241

Authentication

This endpoint uses your Africa’s Talking API credentials configured via environment variables:
  • AT_USERNAME - Your Africa’s Talking username
  • AT_API_KEY - Your Africa’s Talking API key
This endpoint only works with production credentials. Sandbox accounts return simulated balance information.

Balance Monitoring Example

import requests

def check_balance():
    response = requests.get('http://localhost:8000/api/v1/payments/wallet/balance')
    data = response.json()
    
    # Parse balance (remove currency prefix and commas)
    balance_str = data['wallet_balance']['balance']
    amount = float(balance_str.split()[-1].replace(',', ''))
    
    # Alert if low
    if amount < 1000:
        print(f"⚠️ Low balance: {balance_str}")
        # Send alert notification
    
    return amount

# Check balance before large payment
balance = check_balance()
if balance >= payment_amount:
    # Proceed with payment
    pass

JavaScript Example

async function getWalletBalance() {
  const response = await fetch('http://localhost:8000/api/v1/payments/wallet/balance');
  const data = await response.json();
  
  console.log('Current balance:', data.wallet_balance.balance);
  
  return data.wallet_balance;
}

// Monitor balance
getWalletBalance().then(balance => {
  console.log(`Wallet: ${balance.balance} ${balance.currency}`);
});

Best Practices

Rate Limiting: Don’t poll this endpoint too frequently. Balance updates are not real-time and excessive requests may be throttled by Africa’s Talking.Recommended: Check balance once per hour or before large payment batches.
Threshold Monitoring: Set up automated alerts when balance drops below your operational threshold (e.g., 20% of average daily payment volume).

Troubleshooting

Problem: Using sandbox credentialsSolution: This endpoint requires production API credentials to show real balance. Sandbox returns simulated values.
Problem: Invalid API credentials or network issueSolution:
  • Verify AT_API_KEY is set correctly
  • Ensure credentials have payment permissions
  • Check network connectivity to Africa’s Talking API
Problem: Caching or timing delaySolution: Africa’s Talking balance may have a small delay. Check the main dashboard for authoritative balance.

Mobile Checkout

Initiate mobile money payment

Test Payment

Test payment integration

Payment Integration

Complete payment setup guide

Build docs developers (and LLMs) love