How-to guide
How to integrate AzamPay with MikroTik hotspot billing
Updated 19 October 2026 · VillageHub
Short answer
You need a MikroTik router with internet, an AzamPay merchant account with a registered application, and that app's four credentials: App Name, Client ID, Client Secret and API Key. The short version: register the app on the AzamPay developer portal and complete KYC for production keys, link your router to VillageHub with one pasted script, choose AzamPay under Settings, Payments and paste the credentials, copy the webhook URL VillageHub shows into your AzamPay callback settings, then test with a small package. Customers get a mobile money prompt on their phone, and the money settles into your own AzamPay account.
| Item | Where to get it | Cost |
|---|---|---|
| MikroTik router with internet access | Any MikroTik reseller | One-off hardware cost |
| AzamPay merchant account with business KYC | AzamPay (sandbox registration at developers.azampay.co.tz, production keys after KYC) | Transaction fees set in your AzamPay merchant agreement; AzamPay does not publish a public rate card |
| App Name, Client ID, Client Secret, API Key | Your registered application in the AzamPay portal | 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, no payments) | Free software; you build or find the AzamPay plugin and host the callback yourself |
VillageHub prices checked 19 Oct 2026. AzamPay fees are agreed per merchant; ask AzamPay for your rate.
How it works
A customer joins the hotspot, picks a package on the captive portal and enters their phone number. VillageHub asks AzamPay to send a mobile checkout prompt, choosing the network from the number prefix: M-Pesa (Vodacom), Mixx by Yas (Tigo Pesa), Airtel Money, HaloPesa or AzamPesa. When the customer approves with their PIN, AzamPay calls the VillageHub webhook and the package is activated through RADIUS, so the device goes online within seconds.
Step 1: Get your AzamPay credentials
- 1Register an applicationSign in to the AzamPay developer portal and register a new app under My Applications. The sandbox registration page is developers.azampay.co.tz/sandbox/registerapp.
- 2Complete KYC for productionSubmit your business KYC from the portal so AzamPay issues production credentials. If self-service is not available for your account, AzamPay support ([email protected]) issues them.
- 3Copy the four valuesApp Name (exactly as registered, including capital letters), Client ID, Client Secret and API Key. Use the production set: VillageHub calls AzamPay's live checkout, so sandbox keys are rejected.
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 the routerIn Winbox, make sure the WAN works and the router can reach the internet.
- 3Add and provisionRouters, Add Router, then paste the generated script into Winbox New Terminal. On RouterOS 7, if you see "device not allowed", run /system device-mode update mode=advanced first. Guide: https://village-hub.net/doc/routers/winbox-setup
Step 3: Connect AzamPay in VillageHub
- 1Choose AzamPayAdmin panel, Settings, Payments, AzamPay card.
- 2Paste the credentialsFill AzamPay App Name, AzamPay Client ID, AzamPay Client Secret and the API Key, then Save Changes.
- 3Set the webhookCopy the Webhook URL shown under the form. It looks like https://isp.village-hub.net/api/payments/azampay/callback/your-subdomain. Paste it as the callback URL in your AzamPay app settings.
- 4Optional: per-router gatewayA router can use a different gateway or account through the payment override on its page in Routers.
Step 4: Packages and a live test
- 1Create packagesPackages, Add Package: name, price in TZS, duration, speeds and optional data cap. See https://village-hub.net/doc/wifi-packages
- 2Test with a small amountCreate a cheap package such as TZS 500, buy it from your phone on the hotspot, approve the prompt and check that Payments shows it completed and the phone is online.
- 3Finish the portalAdd your logo and colours (https://village-hub.net/doc/branding) and print vouchers for cash customers (https://village-hub.net/doc/vouchers).
Manual router setup vs a billing platform
RouterOS can run a hotspot with local users, but it has no AzamPay integration of its own: a server must request the checkout, receive AzamPay's callback and create the user. With PHPNuxBill you can do this on your own server if a suitable plugin exists or you write one, which suits operators who want full control and can maintain a public HTTPS server. Mikhmon handles vouchers well but takes no online payments. VillageHub runs that part for you in the cloud.
Troubleshooting
- UnAuthorized Access or "Failed to authenticate with AzamPay": the App Name, Client ID or Client Secret do not match an active production app. Check the App Name spelling and ask AzamPay to confirm the app is live; sandbox keys always fail here.
- Prompt never arrives: check the number is a Tanzanian mobile money line on a supported network and has enough balance, then retry once.
- Paid but not activated: check the webhook URL in AzamPay matches the one in VillageHub exactly, including your subdomain.
- Router shows offline: check Routers for its status and re-run the provisioning script once internet works.
Frequently asked questions
Which networks does AzamPay cover?+
VillageHub routes AzamPay prompts to M-Pesa (Vodacom), Mixx by Yas (Tigo Pesa), Airtel Money, HaloPesa and AzamPesa based on the customer's number.
Where does the money go?+
Into your own AzamPay merchant account. VillageHub never holds your collections.
Can I test in the AzamPay sandbox?+
Not through VillageHub, which uses AzamPay production. Test with a small real payment instead.
What does VillageHub cost in Tanzania?+
For hotspot, TZS 20,000 per month minimum or 3% of collections, whichever is higher. PPPoE is TZS 600 per active client. 30-day free trial, no setup fee.
Try VillageHub free for 30 days
Connect a MikroTik, add your payment details and sell your first package. No credit card, no setup fees.