How to set up MikroTik hotspot billing with M-Pesa

How M-Pesa hotspot billing works

A customer joins your WiFi, the MikroTik hotspot redirects them to the captive portal, they pick a package and enter their M-Pesa number. VillageHub sends an STK push (M-Pesa Express) through your Daraja app, the customer enters their PIN, Safaricom confirms the payment and VillageHub activates the package through RADIUS. The router lets the device online within seconds and cuts it off when the package time or data runs out.

The portal keeps checking the payment status while the customer waits, so activation does not depend only on the Safaricom callback arriving. Every payment is recorded under Payments in the admin panel with the M-Pesa reference.

Step 1: Get live M-Pesa API credentials from Daraja

1. 1Create a Daraja accountRegister at developer.safaricom.co.ke as a company and log in.
2. 2Create an appGo to My Apps, create a new app and tick Lipa Na M-Pesa Online (M-Pesa Express / STK push). Note the Consumer Key and Consumer Secret.
3. 3Go LiveStart the Go Live process on the Daraja portal for your Paybill or Till. Safaricom usually approves in 24 to 48 hours. Go Live gives you the production app keys and the Lipa Na M-Pesa Online Passkey for your shortcode.
4. 4Use the live values onlySandbox keys and the test shortcode 174379 do not work on VillageHub, which calls the production Safaricom API. Keep the Consumer Key, Consumer Secret, Shortcode and Passkey from the live app together.

Step 2: Link your MikroTik router to VillageHub

1. 1Create your accountSign up at https://village-hub.net/register, verify your email, then open Settings, General and set the currency to KES.
2. 2Give the router internetConnect to the router with Winbox and make sure the WAN (DHCP client or PPPoE) works and the router can ping an outside address.
3. 3Add the routerIn the admin panel go to Routers, Add Router and enter a name and location. VillageHub generates the RADIUS secret and a configuration script.
4. 4Paste the scriptOpen New Terminal in Winbox, paste the script and press Enter. It sets up the hotspot, RADIUS and the secure tunnel. If RouterOS 7 refuses with "device not allowed", run /system device-mode update mode=advanced, confirm on the router, and paste again. Full walkthrough: https://village-hub.net/doc/routers/winbox-setup

Step 3: Enter your M-Pesa keys in VillageHub

1. 1Open the payment settingsAdmin panel, Settings, Payments. Choose the card "M-Pesa (Daraja API)", which is the gateway "M-Pesa Paybill / Till Number With API keys".
2. 2Pick the method of paymentChoose Paybill or Till (Buy Goods) to match your shortcode. This decides whether the STK push is sent as a Paybill or a Buy Goods payment.
3. 3Fill in the four fieldsM-Pesa Shortcode (your Paybill or Till number), M-Pesa Passkey, Consumer Key and Consumer Secret. Save. You do not need to register a callback URL in Daraja: VillageHub sends its own callback address with every STK push.
4. 4Optional: different till per siteIf one site collects into a different Paybill or Till, open that router in Routers and set a payment override. That router then uses its own gateway and keys while the rest use the tenant setting.

Step 4: Create packages and test a payment

1. 1Create packagesGo to Packages, Add Package. Set a name, price in KES, duration, upload and download speed, and an optional data cap. Packages show on the captive portal of every router. Details: https://village-hub.net/doc/wifi-packages
2. 2Add a test packageMake a KES 1 or KES 10 package so you can test with real money cheaply.
3. 3Buy it from a phoneJoin the hotspot, pick the test package, enter your M-Pesa number and approve the PIN prompt. Check that the payment shows as completed under Payments and that the phone gets internet.
4. 4Brand the portalUpload your logo and colours so customers recognise the network: https://village-hub.net/doc/branding. You can also print vouchers for cash sales: https://village-hub.net/doc/vouchers

Doing it yourself on the router vs using a billing platform

MikroTik alone can run a hotspot with local users and printed vouchers, but it cannot take M-Pesa payments by itself. Something has to receive the Daraja callback, create the user and push it to the router. Mikhmon is a popular free voucher manager for that local approach, but it has no payment gateway. PHPNuxBill is open source, supports RADIUS and Hotspot and PPPoE, and adds payment gateways through plugins, so it is a good choice if you are comfortable running a public server with HTTPS and keeping it patched.

VillageHub is the hosted option: the portal, RADIUS, M-Pesa integration, SMS receipts and router monitoring are run for you, and you pay a share of collections instead of running a server.

Troubleshooting

• No PIN prompt arrives: check the number is a Safaricom line, the phone is on and unlocked, and the four Daraja values all come from the same live app. Sandbox keys fail on production.
• Error 2002 "The Agent number and Store number entered do not match": the shortcode, passkey and method do not belong together. Confirm with Safaricom which shortcode your live Lipa Na M-Pesa Online product is bound to and that the method (Paybill or Till) matches it.
• Invalid credentials or 401 from Safaricom: the Consumer Key or Secret is from the sandbox app or was regenerated. Copy them again from the live app.
• Customer paid but is not online: ask them to keep the portal page open for a few seconds after paying. If the device was disconnected, they can reconnect and log in with the account shown on the portal. Check Payments for the transaction status.
• The portal does not appear at all: the router is not linked. Check Routers for its status and re-run the script with internet working.

Frequently asked questions

Sources

• Safaricom Daraja developer portal
• Business Today: Safaricom cuts M-Pesa merchant charges (31 Jul 2026)
• MikroTik Winbox download
• Mikhmon v3 on GitHub
• PHPNuxBill on GitHub

Related