Top up the wallet via M-Pesa

Two ways to put KES in your wallet: trigger an STK push over the API so the payer just enters their M-Pesa PIN, or pay the paybill manually with your account number. Both credit the wallet automatically.

Wallet funds pay the one-time and service fees on the platform — most importantly sender ID registrations, shortcode deposits and USSD setup fees. Keep the wallet funded whenever you have applications in review.

Option 1 — STK push over the API

POST/api/v1/wallet/stk-push

Parameters

Field	Type	Required	Description
phone	string	Yes	The M-Pesa number to charge — the payer gets the PIN prompt on this phone. Any accepted format.
amount	number	Yes	KES amount, 1 – 70,000 (the M-Pesa per-transaction ceiling).

curl -X POST https://api.mobilesasa.com/api/v1/wallet/stk-push \
  -H "Authorization: Bearer $MOBILESASA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "0712345678",
    "amount": 5000
  }'

Response — 200

{
  "success": true,
  "data": { "message": "STK push sent. Check your phone to complete payment." }
}

The credit is asynchronous

A 200 here means the PIN prompt was dispatched — not that money moved. The wallet is credited when Safaricom confirms the payment, usually within seconds of the payer entering their PIN. Confirm by polling the wallet ledger for a credit entry carrying the M-Pesa receipt number.

Option 2 — manual paybill

Anyone can top up your wallet from the M-Pesa menu, no API involved:

Paybill details

Field	Type	Required	Description
Paybill	business number	No	4078003
Account	reference	No	Your team's `local_account_no` — read it from GET /api/v1/units/balance.
Amount	KES	No	Whatever you need. Credited automatically on Safaricom's confirmation callback.

Confirming a top-up

Whichever route the money took, it lands the same way — poll the wallet ledger and match on the receipt:

curl "https://api.mobilesasa.com/api/v1/units/wallet/ledger?page=1&page_size=10" \
  -H "Authorization: Bearer $MOBILESASA_TOKEN"

Response — 200

{
  "success": true,
  "data": [
    {
      "uuid": "f302…",
      "entry_type": "credit",
      "amount": 5000.00,
      "description": "M-Pesa deposit",
      "mpesa_receipt": "SGH8KL2M9Q",
      "created_at": "2026-07-11T14:03:51Z"
    }
  ],
  "meta": { "page": 1, "page_size": 10, "total": 1 }
}

The wallet is not SMS sending credit

The wallet is KES for fees; message sending spends SMS units from a separate balance. Topping up the wallet does not add sending credit — unit purchases are a separate flow (see the portal, or talk to your account manager for bulk rates).