Billing

Balance & Top-up

Read your wallet balance and start a top-up via mobile money or card — all programmatically. Every message debits this single TZS wallet.

MailAfrica is pay-per-message from a single TZS wallet. No subscriptions. Every inbound message and every outbound recipient debits your balance; sends are refunded if the provider fails.

Read your balance

bash

curl https://api.mailafrica.online/api/billing/balance \
  -H "X-API-Key: MAIL_<your_api_key_here>"

json

{
  "success": true,
  "data": { "balance_tzs": 45000 },
  "request_id": "req_01",
  "timestamp": "2026-08-15T00:00:00Z"
}

When the balance is too low to cover an inbound message, the message is rejected; outbound sends return 402 INSUFFICIENT_BALANCE. Monitor balance and alert before it runs dry.

Start a hosted top-up

POST /api/billing/topup creates a hosted payment page and returns the checkout URL to send your customer to. Supported payment methods are mobile money and card:

bash

curl -X POST https://api.mailafrica.online/api/billing/topup \
  -H "X-API-Key: MAIL_<your_api_key_here>" \
  -H "Content-Type: application/json" \
  -d '{"amount_tzs": 20000}'

json

{
  "success": true,
  "data": {
    "topup": {
      "id": 88,
      "user_id": 7,
      "amount_tzs": 20000,
      "status": "pending",
      "provider_reference": null,
      "created_at": "2026-08-15T00:00:00Z"
    },
    "checkout_url": "https://pay.mailafrica.online/checkout/...",
    "payment_link_url": "https://...",
    "provider_reference": "ref_123"
  }
}

Minimum amount is 2,000 TZS. The checkout link expires after 1 hour. Once payment completes, your balance credits automatically.

USSD push top-up

If your account has a verified phone number, you can trigger a direct USSD mobile-money push instead of a hosted page:

bash

curl -X POST https://api.mailafrica.online/api/billing/topup/phone \
  -H "X-API-Key: MAIL_<your_api_key_here>" \
  -H "Content-Type: application/json" \
  -d '{"amount_tzs": 10000}'

Without a verified phone number this returns 400 VALIDATION_ERROR. Add and verify your phone via Authentication.

Tracking payments

Top-ups move through pending → completed | failed. Payment status updates arrive from our payment gateway; poll GET /api/billing/balance to see credits land (events payment.completed credit your balance; payment.failed/expired/voided mark the top-up failed).

You can also top up from the dashboard at app.mailafrica.online — same wallet, same balance.