> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyberpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Hotspot Setup
> Configure captive portal hotspots with login pages, vouchers, and bandwidth packages.
## Overview
FyberPay supports hotspot-based internet access alongside PPPoE. Hotspots use a captive portal (login page) where subscribers authenticate before gaining internet access. This is ideal for public Wi-Fi locations, apartment complexes, and pay-as-you-go internet cafes.
Hotspot authentication flows through the same RADIUS infrastructure as PPPoE, so billing, dunning, and provisioning all work identically.
## MikroTik Hotspot Server Setup
The recommended path is to let FyberPay create and manage the hotspot server for you via the **NasService** model. Each hotspot service you create through the FyberPay UI is reconciled into the right combination of `/ip/hotspot`, `/ip/dhcp-server`, `/ip/pool`, and walled-garden rules on the live router.
The MikroTik must be connected to FyberPay first. Follow the [MikroTik integration guide](/integrations/mikrotik) to register the device, run the bootstrap script, and confirm the SSTP tunnel is online.
In the FyberPay admin, go to **Network → Gateways**, click your MikroTik, and scroll to **Customer Services**. Click **Add service**, then:
* **Type**: Hotspot
* **Parent interface**: pick the interface customers will connect through. The dropdown groups options by type (Bridges, Ethernet, SFP, VLAN). For multi-port hotspots (a downstream switch or AP feeding multiple ether ports), pick a bridge. See the [bridge-as-parent guide](/guides/mikrotik-bridge-as-parent) for the typical setup.
* **VLAN ID**: leave blank unless you're trunking VLANs.
Click **Create service**.
Behind the scenes, FyberPay creates these resources on the router (each tagged with `comment=FyberPay-svc:`):
* `/ip/hotspot/profile` with the captive portal redirect target
* `/ip/address` on the parent interface (a `/24` from `10.50.0.0/16`)
* `/ip/pool` for client addresses
* `/ip/dhcp-server` and `/ip/dhcp-server/network` bound to the interface
* `/ip/hotspot` server bound to the parent interface, using FreeRADIUS for auth/acct
* Default walled-garden entries (FyberPay payment portal, M-Pesa endpoints)
The service appears as a card in the Customer Services panel. State flips from `pending` to `active` once the reconciler finishes.
Connect a phone to one of the parent interface's member ports (or an AP plugged into one of those ports). The phone should hit the captive portal automatically. Buy a voucher or enter credentials, and the phone should authenticate against FreeRADIUS and get internet at the package speed.
The legacy approach of running `/ip/hotspot/setup` manually on the router and pointing RADIUS at FyberPay still works, but you lose drift detection, hard-cut reconfigure, and the walled-garden auto-management. New deployments should use the NasService flow.
FyberPay uses the same RADIUS database for both PPPoE and hotspot authentication. Subscribers with access method set to "hotspot" are provisioned identically in `radcheck` and `radusergroup`, but they authenticate through the captive portal instead of a PPPoE client.
## Captive Portal Customization
FyberPay renders the captive portal page server-side per organization. You don't upload `login.html` to the router. Instead, you pick a theme and a few branding fields in the admin UI, FyberPay generates the HTML, and the next page load on any hotspot served by your routers picks up the new look automatically.
### Default Login Flow
1. Subscriber connects to the Wi-Fi network
2. On opening a browser, they are redirected to FyberPay's hosted captive portal
3. They either:
* Enter a voucher code (one-tap login) **or**
* Buy a package directly with M-Pesa (STK Push) and the portal auto-logs them in once payment confirms
4. RADIUS authenticates and returns bandwidth limits to MikroTik
5. The subscriber is redirected to the configured post-login URL (or to their original destination)
### Configuring the portal
Navigate to **Hotspot → Portal** in the admin. The configuration form has these fields:
| Field | What it controls | Notes |
| --------------------------- | ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Theme** | The overall visual design | Five built-in themes: `classic`, `modern`, `minimal`, `vibrant`, `dark`. Each ships with its own typography, layout, and motion language. Pick the one that matches your brand. |
| **Logo URL** | The image shown above the form | HTTPS URL to a PNG or SVG. Recommended: 200×60px or smaller. |
| **Primary colour** | The main accent (buttons, links) | Hex format `#RRGGBB`. |
| **Accent colour** | Secondary highlights (badges, focus rings) | Hex format `#RRGGBB`. |
| **Headline** | The big message above the form | Up to 120 characters. |
| **Subheadline** | The smaller line below the headline | Up to 200 characters. |
| **Post-login redirect URL** | Where users land after successful auth | Optional. If unset, MikroTik's default `$(link-orig)` is used (the page they were originally trying to reach). |
There is a **live preview** panel that re-renders as you type, so you can see exactly what subscribers will see.
The portal is **server-rendered on every connect**, so updates take effect on the next page load. No MikroTik push needed, no router restart, no DNS cache to wait on. Saving the form is the deploy.
### Themes
| Theme | Best for |
| --------- | ---------------------------------------------------------------------------- |
| `classic` | Traditional ISPs that want a professional, conservative feel |
| `modern` | Tech-forward brands; clean grid + gradient accents |
| `minimal` | Operators who want the portal to feel invisible (logo + form, not much else) |
| `vibrant` | High-energy brands; bold colour usage and animation |
| `dark` | Low-light environments (cafes, lounges) and modern aesthetic |
You can switch themes anytime. Existing subscribers see the new theme on their next captive-portal hit (typically the next time they connect to Wi-Fi).
### Per-router branding behaviour
The hotspot service the reconciler creates on each router points to FyberPay's hosted portal URL. Every router serving your subscribers redirects to the same portal endpoint, scoped by your org subdomain. You set the branding once and it applies everywhere.
If you need different branding per location (e.g. one ISP managing several venues with their own logos), each venue should be a separate FyberPay org / subdomain.
## Voucher and Package Management
### Creating Hotspot Packages
Hotspot packages are created as regular plans in FyberPay. Navigate to **Billing > Plans** and create a plan with these considerations:
For hourly or daily access:
* Set **Billing Cycle** to the access duration (e.g., 1 day = 1 billing cycle day)
* Set **Speed** to the desired bandwidth
* Set **Price** to the package cost
Examples:
| Package | Speed | Duration | Price |
| ------- | ------- | -------- | --------- |
| 1 Hour | 5 Mbps | 1 day | KES 20 |
| Daily | 10 Mbps | 1 day | KES 50 |
| Weekly | 10 Mbps | 7 days | KES 200 |
| Monthly | 20 Mbps | 30 days | KES 1,000 |
For volume-based access, configure data caps on your MikroTik router using simple queues or RADIUS attributes. FyberPay handles the billing side; the data cap enforcement is done at the router level.
Set up a queue rule on MikroTik that monitors bytes transferred and disconnects the session when the cap is reached.
### Generating Vouchers
Vouchers are pre-generated credentials that subscribers use to log in to the hotspot. Each voucher is a one-time-use code tied to a specific package.
Go to **Billing > Vouchers** in the admin dashboard.
Choose the hotspot plan that vouchers should be generated for.
Enter the number of vouchers to generate (e.g., 100).
Click **Generate**. FyberPay creates unique voucher codes and provisions RADIUS credentials for each one. Download the batch as a printable PDF (voucher cards) or CSV.
Each voucher code is a unique PPPoE/hotspot username with a pre-set password. When a customer enters the voucher code on the login page, RADIUS authenticates them and applies the package's bandwidth limits.
### Voucher Distribution
Common distribution methods for ISPs:
* **Printed voucher cards**: Download the PDF and cut into individual cards for physical resale
* **SMS delivery**: Sell via M-Pesa and have FyberPay SMS the voucher code to the buyer's phone
* **Self-service portal**: Customers purchase packages directly from `yourorg.fyberpay.com/portal/buy` and receive credentials instantly
## Bandwidth Limits Per Package
Each hotspot package enforces bandwidth through the same RADIUS mechanism as PPPoE. When you create a plan in FyberPay:
1. FyberPay writes the `Mikrotik-Rate-Limit` attribute to `radgroupreply`
2. When the hotspot user authenticates, MikroTik receives the rate-limit from RADIUS
3. A dynamic simple queue is created on the router for that session
### Example Package Configuration
| Package | Download | Upload | Burst | Price |
| -------------- | -------- | ------- | ------------------ | ----------- |
| Basic Wi-Fi | 5 Mbps | 2 Mbps | None | KES 50/day |
| Standard Wi-Fi | 10 Mbps | 5 Mbps | 15/8 Mbps for 10s | KES 100/day |
| Premium Wi-Fi | 25 Mbps | 10 Mbps | 40/15 Mbps for 10s | KES 200/day |
Burst settings give users a temporary speed boost when they first start downloading, improving perceived performance for web browsing.
## Session Timeouts
Configure session limits to control how long a hotspot user stays connected:
### MikroTik Session Limits
On your MikroTik hotspot server profile, configure:
| Setting | Description | Recommended Value |
| --------------------- | -------------------------------------------------------- | -------------------------------------------------- |
| **Session Timeout** | Maximum session duration before forced re-authentication | Match billing cycle (e.g., 24h for daily packages) |
| **Idle Timeout** | Disconnect after inactivity period | 15-30 minutes |
| **Keepalive Timeout** | Interval for checking if client is still connected | 30 seconds |
### RADIUS Session Control
FyberPay can also send session timeout attributes via RADIUS:
* `Session-Timeout`: Maximum seconds before disconnect
* `Idle-Timeout`: Seconds of idle before disconnect
These are set per plan in the `radgroupreply` table alongside the rate-limit attribute.
For time-based packages, set the `Session-Timeout` RADIUS attribute to match the package duration. A 1-hour package would have `Session-Timeout = 3600`.
## Walled Garden
The walled garden allows unauthenticated hotspot users to reach specific websites without logging in. This is essential for the captive portal (so users can see it before they authenticate), for M-Pesa STK Push (the user's phone needs to reach Safaricom before they have internet), and for FyberPay's payment callbacks.
### What FyberPay manages automatically
When the reconciler creates a hotspot service, it also sets up the walled-garden defaults that FyberPay's flow needs:
| Destination | Reason |
| ------------------------------------------ | ------------------------------------------- |
| FyberPay's hosted portal endpoint | The captive portal itself |
| `*.safaricom.co.ke`, `api.safaricom.co.ke` | M-Pesa Daraja API for STK Push |
| FyberPay's payment callback URLs | So Daraja's callback can reach the platform |
| DNS (UDP/TCP 53) | Name resolution for unauthenticated clients |
You don't need to add these manually. They live in the service's walled-garden config and are reconciled on every apply.
### Adding custom entries
If your ISP wants to allow unauthenticated access to additional sites (your own marketing page, a partner portal, a help-desk URL), add them via the FyberPay UI on the service's card. The reconciler picks up the change on the next reconcile and pushes the entries to `/ip/hotspot/walled-garden` and `/ip/hotspot/walled-garden/ip`.
Avoid wildcard entries to general domains (`*.com`, `*.google.com`). Anything in the walled garden bypasses your authentication entirely.
### Manual walled-garden management (legacy)
If you bypassed the NasService flow and configured the hotspot manually with `/ip/hotspot/setup`, you'll need to manage the walled garden yourself:
```routeros theme={null}
/ip hotspot walled-garden ip
add dst-host=*.safaricom.co.ke action=accept
add dst-host=api.safaricom.co.ke action=accept
add dst-port=53 protocol=udp action=accept
add dst-port=53 protocol=tcp action=accept
```
This is supported but not recommended for new deployments.
## Hotspot with FyberPay Billing
The full hotspot billing flow ties together the captive portal, RADIUS, and M-Pesa:
1. **Customer connects** to the Wi-Fi network
2. **Captive portal** redirects to the login page
3. **Customer buys a package** via M-Pesa on the walled-garden payment portal
4. **FyberPay receives payment**, creates a subscription, and provisions RADIUS credentials
5. **Credentials are sent** to the customer via SMS
6. **Customer logs in** on the captive portal
7. **RADIUS authenticates** and returns bandwidth limits to MikroTik
8. **Customer gets internet** at the package speed for the package duration
FyberPay charges a hotspot commission as a percentage of voucher revenue. The exact rate is configured per-org and visible at **Settings → Billing** under "Hotspot commission rate".
**Important**: commission is **accrued per voucher purchase and billed on the monthly platform invoice** — it is **not** deducted at payment time. Subscribers see the full voucher amount go through; settlement to your ISP also reflects the full amount minus only the M-Pesa B2B fee on the payout. The hotspot commission shows up as a separate line on your monthly platform bill alongside the per-subscriber platform fee.
## Next Steps
Deep dive into RADIUS, PPPoE profiles, and bandwidth shaping.
Automate payment collection for overdue hotspot and PPPoE subscribers.