Top-ups & billing

Billing is prepaid. You hold a credit balance, and each message is debited as you send.

How you are charged

One SMS is 160 GSM-7 characters. Longer messages split into parts and are billed per part.
Credit is reserved the moment you send, and refunded automatically if a send fails.
Prices drop with volume. See pricing.

Check your balance

curl

curl https://api.sms.pesarails.com/v1/balance \
  -H "Authorization: Bearer YOUR_API_KEY"

200 OK

{ "balanceKes": 499.5 }

Top up

Start a top-up with M-Pesa or Paystack. M-Pesa sends an STK push to the phone; Paystack returns a payment link.

M-Pesa

curl https://api.sms.pesarails.com/v1/topups \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "provider": "mpesa", "amountKes": 1000, "phone": "254712345678" }'

200 OK

{
  "paymentId": "pay_8812",
  "provider": "mpesa",
  "status": "pending",
  "customerMessage": "Enter your M-Pesa PIN to complete the payment"
}

Note

Top-ups confirm asynchronously. Your balance updates the moment the payment is confirmed, and each payment is credited exactly once. Poll GET /v1/topups/:id or watch your balance.

Most teams top up from the dashboard in two taps, the API is there for automated top-ups.