Query Merchant Balance

Check your current merchant account balance before creating vouchers or for dashboard displays.

Endpoint

GET /query_balance

Request

No request body is required. Authentication is handled through headers only as all other endpoints.

Example Request

cURL:

curl -X GET https://payments.pesavoucher.com/api/v1/query_balance \
  -H "X-API-KEY: your_api_key" \
  -H "X-API-SECRET: your_api_secret"

JavaScript (Fetch):

const response = await fetch('https://payments.pesavoucher.com/api/v1/merchant/balance', {
  method: 'GET',
  headers: {
    'X-API-KEY': 'your_api_key',
    'X-API-SECRET': 'your_api_secret'
  }
});

const data = await response.json();
console.log(data);

Response

Success Response

HTTP Status: 200 OK

{
  "success": true,
  "merchant_id": "550f8499-e29b-61d4-a816-446655449900",
  "merchant_name": "NEO Vouchers LTD",
  "balance": 125750.00,
  "currency": "KES",
  "timestamp": "2025-11-26 15:30:45"
}

Response Fields

Field	Type	Description
`success`	boolean	Indicates if the request was successful
`merchant_id`	string (UUID)	Your unique merchant identifier
`merchant_name`	string	Your registered business name
`balance`	float	Current account balance
`currency`	string	Currency code (always "KES")
`timestamp`	string	Server timestamp (Y-m-d H:i:s format)

Error Responses

401 Unauthorized - Missing Credentials

{
  "success": false,
  "error": "API credentials required",
  "timestamp": "2025-11-26 15:30:45"
}

401 Unauthorized - Invalid Credentials

{
  "success": false,
  "error": "Invalid merchant",
  "timestamp": "2025-11-26 15:30:45"
}

404 Not Found - Merchant Not Found

{
  "success": false,
  "error": "Merchant account not found",
  "timestamp": "2025-11-26 15:30:45"
}

405 Method Not Allowed

{
  "success": false,
  "error": "Method not allowed. Use GET request",
  "timestamp": "2025-11-26 15:30:45"
}

500 Internal Server Error

{
  "success": false,
  "error": "Internal server error message",
  "timestamp": "2025-11-26 15:30:45"
}

HTTP Status Codes

Code	Description
`200`	Success - Balance retrieved
`401`	Unauthorized - Invalid or missing credentials
`404`	Not Found - Merchant account doesn't exist
`405`	Method Not Allowed - Must use GET request
`500`	Internal Server Error - Server-side issue

Example Use Cases

1. Pre-Transaction Balance Check

Verify sufficient funds before creating a voucher:

async function createVoucherWithBalanceCheck(amount) {
  // Check balance first
  const balanceResponse = await fetch('/api/v1/merchant/balance', {
    headers: {
      'X-API-KEY': API_KEY,
      'X-API-SECRET': API_SECRET
    }
  });
  
  const balanceData = await balanceResponse.json();
  
  if (!balanceData.success) {
    throw new Error('Could not retrieve balance');
  }
  
  if (balanceData.balance < amount) {
    alert(`Insufficient balance. Available: KES ${balanceData.balance}`);
    return;
  }
  
  // Proceed with voucher creation
  const createResponse = await fetch('/api/v1/create_voucher', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-API-KEY': API_KEY,
      'X-API-SECRET': API_SECRET
    },
    body: JSON.stringify({
      email: 'customer@example.com',
      amount: amount,
      currency: 'KES'
    })
  });
  
  // Handle voucher creation response...
}

2. Low Balance Alert

Monitor balance and alert when it falls below a threshold:

function checkAndAlertLowBalance($threshold = 10000) {
    $ch = curl_init('https://payments.pesavoucher.com/api/v1/merchant/balance');
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER, [
        'X-API-KEY: ' . API_KEY,
        'X-API-SECRET: ' . API_SECRET
    ]);
    
    $response = curl_exec($ch);
    $data = json_decode($response, true);
    curl_close($ch);
    
    if ($data['success'] && $data['balance'] < $threshold) {
        // Send alert email
        mail(
            'admin@yoursite.com',
            'Low Balance Alert',
            "Your merchant balance is low: KES {$data['balance']}"
        );
    }
    
    return $data;
}

Best Practices

Cache the balance - Don't query on every page load. Cache for 1-5 minutes depending on your needs.
Check before creating vouchers - Always verify sufficient balance before attempting to create a voucher to provide better UX.
Handle errors gracefully - Display user-friendly messages when balance cannot be retrieved.
Secure your credentials - Never expose API keys in client-side code. Make balance requests from your backend.
Monitor regularly - Set up automated alerts for low balance conditions.
Rate limiting - Implement reasonable rate limits on your end (e.g., max 1 request per minute for balance checks).