How-to guide
How to integrate ClickPesa with MikroTik hotspot billing
Updated 19 October 2026 · VillageHub
Short answer
You need a MikroTik router with internet, a KYC-verified ClickPesa merchant account, and an API application's Client ID and API Key. The short version: create the app under Settings, Developers in the ClickPesa dashboard, link your router to VillageHub with one pasted script, choose ClickPesa under Settings, Payments and paste the two values, add the VillageHub webhook URL to ClickPesa, and test with a small package. Customers get a USSD payment prompt and are connected when they pay, and the money lands in your own ClickPesa account.
| Item | Where to get it | Cost |
|---|---|---|
| MikroTik router with internet access | Any MikroTik reseller | One-off hardware cost |
| ClickPesa merchant account, KYC approved | merchant.clickpesa.com | Collection fees per ClickPesa's merchant pricing; ask ClickPesa for your rate |
| API application: Client ID and API Key | ClickPesa dashboard, Settings, Developers | Included |
| Billing system (captive portal, RADIUS, packages) | VillageHub at village-hub.net/register | Hotspot: TZS 20,000 per month minimum or 3% of collections, whichever is higher. 30-day free trial, no setup fee |
| Self-hosted alternative | PHPNuxBill (open source, gateways as plugins) or Mikhmon (vouchers only) | Free software; you host and maintain the server and callback |
ClickPesa limits checked 19 Oct 2026 from docs.clickpesa.com. VillageHub prices checked 19 Oct 2026.
How it works
The customer picks a package on your captive portal and enters their number. VillageHub asks ClickPesa to send a USSD push to that phone (M-Pesa, Mixx by Yas / Tigo Pesa, Airtel Money or HaloPesa). Once the customer approves, ClickPesa notifies VillageHub through the webhook, the portal also checks the status, and the package is activated through RADIUS on your MikroTik.
ClickPesa has no sandbox: every request runs against live production and moves real money. Until KYC is approved, ClickPesa limits an account to TZS 100,000 in total across collections, payouts, deposits and withdrawals, and 100 API calls per day.
Step 1: Create your ClickPesa API application
- 1Open DevelopersLog in to merchant.clickpesa.com, open Settings and click Developers.
- 2Create the applicationClick Create Application, give it a name, choose API as the integration type and enable the Payment API (collections).
- 3Copy the Client ID and API KeyThe Client ID stays visible in the app settings. The API Key is shown only once when it is created, so copy it straight away. If you lose it, add a new key under Manage API Keys.
- 4Finish KYCComplete onboarding and KYC so the pre-KYC limits are lifted before you go live with customers.
Step 2: Link your MikroTik router
- 1Create your accountSign up at https://village-hub.net/register and set the currency to TZS under Settings, General.
- 2Prepare and provisionMake sure the router has working internet, then go to Routers, Add Router and paste the generated script into Winbox New Terminal. On RouterOS 7 run /system device-mode update mode=advanced first if the script is refused. Guide: https://village-hub.net/doc/routers/winbox-setup
Step 3: Connect ClickPesa in VillageHub
- 1Choose ClickPesaAdmin panel, Settings, Payments, ClickPesa card.
- 2Paste the credentialsEnter the ClickPesa Client ID and API Key and save.
- 3Add the webhookCopy the Webhook URL VillageHub shows under the form (https://isp.village-hub.net/api/payments/clickpesa/callback/ followed by your account identifier) and paste it into the ClickPesa dashboard under Settings, Developers, Webhooks.
- 4Optional: per-router gatewayUse the payment override on a router's page to collect for that site through a different gateway or account.
Step 4: Packages and a live test
- 1Create packagesPackages, Add Package with price in TZS, duration, speeds and optional data cap. See https://village-hub.net/doc/wifi-packages
- 2Test with real moneyBecause ClickPesa has no sandbox, create a small package such as TZS 100 to 500, buy it from your phone on the hotspot and confirm the payment shows as completed under Payments and the phone gets internet. More detail: https://village-hub.net/doc/clickpesa
- 3Finish the portalBrand the portal (https://village-hub.net/doc/branding) and set up vouchers for cash sales (https://village-hub.net/doc/vouchers).
Manual router setup vs a billing platform
A MikroTik on its own cannot take ClickPesa payments; a server has to request the USSD push, receive the webhook and create the hotspot user. PHPNuxBill can do this on your own server with a gateway plugin, which suits operators who want to self-host and can maintain HTTPS and updates. Mikhmon is good for vouchers but has no online payment. VillageHub handles the portal, RADIUS and ClickPesa link as a hosted service.
Troubleshooting
- Payments stop after a few tries on a new account: you may have hit the pre-KYC limit of TZS 100,000 or 100 API calls per day. Complete KYC with ClickPesa.
- Authentication errors: the API Key was revoked, expired or copied wrongly. Create a new key under Manage API Keys and paste it again.
- Every request fails with 404 or 503 at the same time: the problem is usually on ClickPesa’s side, so check their service status or contact their support before changing your settings.
- Paid but not activated: check the webhook URL in ClickPesa matches the VillageHub one exactly, then look up the transaction under Payments.
- No prompt on the phone: confirm the number is a Tanzanian mobile money line with balance, and that it was entered with the right prefix.
Frequently asked questions
Does ClickPesa have a test mode?+
No. ClickPesa runs everything in production, so test with a small real payment.
Which networks can customers pay with?+
ClickPesa covers M-Pesa (Vodacom), Mixx by Yas (Tigo Pesa), Airtel Money and HaloPesa in Tanzania.
Who holds the money?+
Your ClickPesa merchant account. VillageHub charges its fee separately and never holds collections.
ClickPesa or AzamPay?+
Both cover the main Tanzanian wallets. Pick the one that gives you the better rate and settlement terms; you can switch in Settings, Payments at any time, or run different gateways on different routers.
Try VillageHub free for 30 days
Connect a MikroTik, add your payment details and sell your first package. No credit card, no setup fees.