Wallet & Billing

Base path: /wallet

All SMS sending is prepaid — you top up in KES, and each SMS/campaign debits the wallet at your current per-SMS rate (see Pricing).

Get balance

GET /wallet

{ "balance_kes": 245.50, "total_spent_kes": 1204.75, "total_sms_sent": 2601 }

Pricing & tier info

GET /wallet/pricing — your current tier, rate, and progress to the next tier. See Pricing for the full response shape.

Top up

POST /wallet/topup

{ "amount_kes": 500, "email": "you@example.com" }

Minimum top-up is 50 KES. Returns an authorization_url — redirect the paying user there to complete checkout:

{
  "authorization_url": "https://checkout.example.com/...",
  "access_code": "...",
  "reference": "wakali_...",
  "message": "Redirect user to authorization_url to complete payment."
}

The wallet is credited once the payment is confirmed (via webhook, or when the user is redirected back after paying) — not at the time this endpoint is called.

Transaction history

GET /wallet/transactions?page=1&page_size=20&type=

type filters to one value: topup, debit, refund, or sender_id_fee.

{
  "data": [
    {
      "id": "...",
      "type": "debit",
      "amount_kes": 25.00,
      "sms_count": 50,
      "reference": null,
      "description": "SMS to 50 recipient(s)",
      "created_at": "2026-07-01T09:00:00Z"
    }
  ],
  "page": 1,
  "page_size": 20,
  "total": 340,
  "pages": 17
}