How-to guide
How to integrate Hubtel with MikroTik hotspot billing
Updated 19 October 2026 · VillageHub
Short answer
VillageHub supports Hubtel both as a payment gateway (Direct Receive Money, an inline MoMo prompt on the customer's phone) and as an SMS provider. You need a MikroTik router with internet, a Hubtel merchant account with your POS Sales ID and an API ID and API Key, and Hubtel must enable Direct Receive Money on your keys and whitelist the VillageHub server IP. Then link the router with one pasted script, choose Hubtel (Mobile Money) under Settings, Payments, paste the three values and test with a small package. Payments go into your own Hubtel merchant account.
| Item | Where to get it | Cost |
|---|---|---|
| MikroTik router with internet access | Any MikroTik reseller | One-off hardware cost |
| Hubtel merchant account | hubtel.com (business verification required) | Hubtel charges a percentage per collection; see Hubtel's service fees page for your rate |
| POS Sales ID (Merchant Account / Collection Account Number) | Hubtel app or merchant dashboard | Included |
| API ID and API Key with the Receive Money scope | Programmable API keys in your Hubtel account; scopes are added by your Hubtel Retail Systems Engineer | Included |
| IP whitelisting of the VillageHub server | Request from Hubtel (get the IP from VillageHub support) | Included |
| Billing system (captive portal, RADIUS, packages) | VillageHub at village-hub.net/register | Hotspot: GHS 120 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 the server and would still need Hubtel to whitelist your own IP |
VillageHub prices checked 19 Oct 2026. Confirm Hubtel's current collection fee and e-levy treatment with Hubtel before setting package prices.
What Hubtel does in VillageHub
Payments: the customer picks a package on the captive portal and enters a Ghana mobile number. VillageHub sends a Direct Receive Money request to Hubtel, choosing the channel from the number (MTN MoMo, Telecel Cash or AirtelTigo Money), and the customer approves the prompt with their PIN. VillageHub confirms the payment with Hubtel's transaction status API and also accepts Hubtel's callback, then activates the package through RADIUS.
SMS: separately, Hubtel can send purchase receipts, login details and expiry reminders. You can use Hubtel for payments, SMS or both.
Step 1: Get Hubtel ready for Direct Receive Money
- 1Find your POS Sales IDIn the Hubtel app or dashboard, note your Merchant Account or POS Sales ID. Hubtel also calls this the Collection Account Number.
- 2Create API keysAn Administrator on the Hubtel account creates programmable API keys. Each key has an API ID (the username) and an API Key (the password).
- 3Ask for the scope and whitelistingContact your Hubtel Retail Systems Engineer and ask them to enable the Direct Receive Money (receive mobile money) API on those keys and to whitelist the VillageHub server's public IP. Ask VillageHub support for the IP. Without whitelisting, Hubtel answers 403 Forbidden or times out.
- 4Unsolicited prompt protectionHubtel expects a safeguard against unsolicited payment prompts, for example confirming the customer's phone number before charging. The VillageHub portal collects the number from the customer on the hotspot before any prompt is sent; mention this when Hubtel asks.
Step 2: Link your MikroTik router
- 1Create your accountSign up at https://village-hub.net/register and set the currency to GHS under Settings, General.
- 2Prepare and provisionMake sure the router has 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 Hubtel payments in VillageHub
- 1Choose HubtelAdmin panel, Settings, Payments, Hubtel card (gateway "Hubtel (Mobile Money)").
- 2Enter three valuesPOS Sales ID, API ID and API Key. Save.
- 3Callback URLVillageHub shows a Callback URL under the form. You do not paste it into Hubtel: it is sent with every payment request automatically.
- 4Optional: per-router gatewayA router can collect through a different gateway using the payment override on its page in Routers.
Step 4: Add Hubtel SMS (optional)
- 1Get SMS credentialsIn the Hubtel developer portal, under API Accounts, copy the Client ID and Client Secret, and register an alphanumeric Sender ID of up to 11 characters.
- 2Configure in VillageHubSettings, Manage Notifications, Gateway Settings: set SMS Provider to Hubtel (Ghana), paste the Client ID, Client Secret and approved Sender ID. Numbers are formatted to +233 automatically. Details: https://village-hub.net/doc/sms-hubtel
Step 5: Packages and a live test
- 1Create packagesPackages, Add Package with price in GHS, duration, speeds and optional data cap. See https://village-hub.net/doc/wifi-packages
- 2TestCreate a GHS 1 package, buy it on the hotspot with your own MoMo number, approve the prompt and check that Payments shows it completed and the phone is online. Ask customers to keep the portal open until they are connected.
- 3Finish the portalBrand it (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
RouterOS cannot call Hubtel by itself. If you self-host PHPNuxBill you need a Hubtel gateway plugin and a server with a fixed public IP that Hubtel whitelists, plus HTTPS and maintenance. Mikhmon manages vouchers but takes no online payments. With VillageHub, the whitelisted server, portal, RADIUS and payment confirmation are already in place, and you only provide your own Hubtel keys.
Troubleshooting
- 403 Forbidden or timeouts: the VillageHub server IP is not whitelisted on your Hubtel account yet.
- Error 4101: the API keys lack the receive money scope or the POS Sales ID is wrong. Ask your Hubtel Retail Systems Engineer to add the scope.
- Error 4105: the POS Sales ID does not belong to the same Hubtel account as the API ID and API Key.
- Number rejected before any prompt: Hubtel payments only accept Ghana mobile numbers (233 followed by 9 digits).
- Customer approved late and was not connected: payments approved after the portal is closed are picked up by a background status check a few minutes later. Ask the customer to reconnect to the WiFi and open the login page again.
- SMS not delivered: the Sender ID is not approved yet, or the SMS Client ID and Secret are the payment API keys by mistake.
Frequently asked questions
Is Hubtel a payment gateway in VillageHub or only SMS?+
Both. Hubtel Direct Receive Money is a live payment gateway, and Hubtel SMS is a separate notification provider.
Which wallets can customers use?+
MTN MoMo, Telecel Cash and AirtelTigo Money, picked automatically from the customer's number.
Do I need to set a callback URL in Hubtel?+
No. VillageHub sends its callback address with each request and also checks the transaction status itself.
What does VillageHub cost in Ghana?+
Hotspot is GHS 120 per month minimum or 3% of collections, whichever is higher. PPPoE is GHS 4 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.