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).