Skip to main content

Wallet & Credits

AfriRoute runs on a pre-funded wallet. You top up a balance, and each delivered message, call, or transaction draws down against it in real time. This keeps spend predictable, prevents bill shock, and works well in markets where post-paid credit is impractical.

How the Wallet Works​

  1. Top up your wallet via mobile money, card, or bank transfer.
  2. Send SMS, voice, WhatsApp, or payments.
  3. Each delivered unit is deducted from your balance at the applicable rate.
  4. Auto-recharge (optional) tops you back up before you run dry.

Check Your Balance​

curl https://api.afriroute.ai/api/v1/wallet/balance \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY"
{
  "balance": 1542.75,
  "currency": "USD",
  "reserved": 12.40,
  "available": 1530.35,
  "last_topup": "2026-05-20T10:00:00Z",
  "low_balance_threshold": 100.00
}

reserved covers in-flight messages awaiting delivery confirmation; available is what you can spend right now.

Top Up​

curl -X POST https://api.afriroute.ai/api/v1/wallet/topup \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 500,
    "currency": "USD",
    "payment_method": "mpesa",
    "phone_number": "+254712345678"
  }'
{
  "topup_id": "top_abc123",
  "status": "pending",
  "amount": 500,
  "currency": "USD",
  "new_balance_on_completion": 2042.75
}

Card and mobile money top-ups credit instantly on confirmation; bank transfers credit on receipt (usually same or next business day).

Auto-Recharge​

Avoid service interruption by configuring an auto-recharge rule. When available falls below trigger_amount, AfriRoute charges your saved payment method for recharge_amount.

curl -X POST https://api.afriroute.ai/api/v1/wallet/auto-recharge \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "trigger_amount": 100,
    "recharge_amount": 500,
    "payment_method_id": "pm_card_visa_4242",
    "max_recharges_per_day": 3
  }'

The max_recharges_per_day cap protects you against runaway spend if a campaign misbehaves.

Low-Balance Alerts​

Set a threshold and AfriRoute will email and webhook you before you run out:

curl -X PATCH https://api.afriroute.ai/api/v1/wallet/settings \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY" \
  -d '{ "low_balance_threshold": 200, "alert_email": "[email protected]" }'

Webhook payload:

{ "event": "wallet.low_balance", "balance": 185.40, "threshold": 200, "currency": "USD" }

Reserved vs Available Balance​

When you submit a message, its estimated cost is reserved immediately so you cannot oversend. On a successful delivery the reservation converts to a charge; on failure it is released back to available. This is why a freshly submitted bulk campaign briefly shows a higher reserved figure.

Multi-Currency​

You may hold a wallet balance in USD or a supported local currency (KES, NGN, ETB, GHS, ZAR). All usage is rated in USD and converted at the daily mid-market rate plus a 1% FX margin, itemized on your statements.

Transaction Ledger​

Every credit and debit is recorded:

curl "https://api.afriroute.ai/api/v1/wallet/ledger?start=2026-05-01&end=2026-05-28" \
  -H "Authorization: Bearer $AFRIROUTE_API_KEY"

Billing questions? [email protected]

Last Updated: May 2026