Balance
You pay for messages from a prepaid naira wallet. GET /v1/balance needs the balance:read scope.
curl 'https://api.messaging.500calls.com/v1/balance' \ -H "Authorization: Bearer $API_KEY_500CALLS"import osimport requestsresponse = requests.get( "https://api.messaging.500calls.com/v1/balance", headers={ "Authorization": f"Bearer {os.environ['API_KEY_500CALLS']}", }, timeout=30,)print(response.status_code, response.json())const response = await fetch("https://api.messaging.500calls.com/v1/balance", { headers: { Authorization: `Bearer ${process.env.API_KEY_500CALLS}`, },});console.log(response.status, await response.json());<?php$curl = curl_init('https://api.messaging.500calls.com/v1/balance');curl_setopt_array($curl, [ CURLOPT_HTTPHEADER => [ 'Authorization: Bearer ' . getenv('API_KEY_500CALLS'), ], CURLOPT_RETURNTRANSFER => true,]);$body = curl_exec($curl);$status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);echo $status, PHP_EOL, $body, PHP_EOL;The fields
| Field | Meaning |
|---|---|
balance | All the money in the wallet, including what is held |
held | Held for messages that are scheduled, queued or being sent, and for finished messages until they are settled, within about a minute |
available | balance minus held: what new sends can use |
low_balance_threshold | Your organisation's low-balance alert threshold |
as_of | When the balance was read |
Amounts are strings with four decimal places next to "currency": "NGN": "15250.0000" is ₦15,250.00. Parse them as decimals, never as floating-point numbers.
A send's hold shows at once: straight after a 202, held includes it and available is lower by the same amount, while balance stays the same. Money charged or released when a message is sent, fails or is cancelled moves within about a minute, when the message is settled. Until then a send that needs that money can get 402 insufficient_balance.
Topping up
Top-ups happen in the dashboard, under Wallet and billing, through Paystack. The API cannot top up.