Balance & Wallet

How billing works

eSMS Africa uses a prepaid wallet model. You deposit funds into your wallet and each message is charged against that balance in real time.

Balance before

1,500.00 USD

Send 100 SMS to Uganda

100 × 35 UGX = 3,500 UGX → −0.94 USD

Balance after

1,499.06 USD

Charges happen at send time - not at delivery. If a message fails, you can request a refund via support.

Check your balance

GET /api/balance

{
  "balance": 1499.06,
  "currency": "USD"
}

Top up

Top up via sms.esmsafrica.io/payment using Flutterwave. Supported payment methods include:

Card (Visa, Mastercard)
Mobile money (M-Pesa, Airtel Money, MTN MoMo)
Bank transfer

Or via API (redirects to the payment portal):

POST /api/balance/topup

Response:

{
  "checkout_url": "https://auth.esmsafrica.io/payments/initiate",
  "message": "Redirecting to payment portal"
}

Transaction history

GET /api/balance/transactions?page=0&limit=20

{
  "transactions": [
    {
      "id": 101,
      "type": "sms_charge",
      "amount": -0.94,
      "balance_after": 1499.06,
      "currency": "USD",
      "description": "SMS to +256712345678 via ESMS_UG (1 seg)",
      "created_at": "2026-05-02T12:00:01Z"
    },
    {
      "id": 100,
      "type": "credit",
      "amount": 100.00,
      "balance_after": 1500.00,
      "currency": "USD",
      "description": "Top up via Flutterwave",
      "created_at": "2026-05-01T09:00:00Z"
    }
  ],
  "total": 87,
  "page": 0,
  "limit": 20
}

Transaction types

Type	Description
`credit`	Funds added via Flutterwave or bank transfer
`sms_charge`	Charged for a sent message
`manual_credit`	Credit applied by the eSMS Africa team
`manual_debit`	Deduction applied by the eSMS Africa team
`refund`	Refund for failed message delivery

Amounts are negative for charges and positive for credits.

Insufficient balance

If your balance is too low to send a message, the API returns:

{
  "detail": {
    "code": "insufficient_balance",
    "message": "Insufficient balance. Required: 35 UGX, available: 10 UGX"
  }
}

For bulk send, the pre-check endpoint (POST /api/messages/bulk-precheck) tells you in advance whether your balance is sufficient.

Low balance alerts

You will receive an in-app notification and email when your balance drops below a configured threshold. Set your threshold in Settings → Notifications.