Skip to main content

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.

​
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.
1

Make sure the router is provisioned

The MikroTik must be connected to FyberPay first. Follow the MikroTik integration guide to register the device, run the bootstrap script, and confirm the SSTP tunnel is online.
2

Pick the parent interface

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 for the typical setup.
  • VLAN ID: leave blank unless you’re trunking VLANs.
Click Create service.
3

What the reconciler does

Behind the scenes, FyberPay creates these resources on the router (each tagged with comment=FyberPay-svc:<service-id>):
  • /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.
4

Verify it works

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:
FieldWhat it controlsNotes
ThemeThe overall visual designFive 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 URLThe image shown above the formHTTPS URL to a PNG or SVG. Recommended: 200×60px or smaller.
Primary colourThe main accent (buttons, links)Hex format #RRGGBB.
Accent colourSecondary highlights (badges, focus rings)Hex format #RRGGBB.
HeadlineThe big message above the formUp to 120 characters.
SubheadlineThe smaller line below the headlineUp to 200 characters.
Post-login redirect URLWhere users land after successful authOptional. 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

ThemeBest for
classicTraditional ISPs that want a professional, conservative feel
modernTech-forward brands; clean grid + gradient accents
minimalOperators who want the portal to feel invisible (logo + form, not much else)
vibrantHigh-energy brands; bold colour usage and animation
darkLow-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:
PackageSpeedDurationPrice
1 Hour5 Mbps1 dayKES 20
Daily10 Mbps1 dayKES 50
Weekly10 Mbps7 daysKES 200
Monthly20 Mbps30 daysKES 1,000

​
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.
1

Navigate to voucher management

Go to Billing > Vouchers in the admin dashboard.
2

Select a package

Choose the hotspot plan that vouchers should be generated for.
3

Set batch size

Enter the number of vouchers to generate (e.g., 100).
4

Generate and print

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

PackageDownloadUploadBurstPrice
Basic Wi-Fi5 Mbps2 MbpsNoneKES 50/day
Standard Wi-Fi10 Mbps5 Mbps15/8 Mbps for 10sKES 100/day
Premium Wi-Fi25 Mbps10 Mbps40/15 Mbps for 10sKES 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:
SettingDescriptionRecommended Value
Session TimeoutMaximum session duration before forced re-authenticationMatch billing cycle (e.g., 24h for daily packages)
Idle TimeoutDisconnect after inactivity period15-30 minutes
Keepalive TimeoutInterval for checking if client is still connected30 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:
DestinationReason
FyberPay’s hosted portal endpointThe captive portal itself
*.safaricom.co.ke, api.safaricom.co.keM-Pesa Daraja API for STK Push
FyberPay’s payment callback URLsSo 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: 
/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 the centralized 1% transaction fee if applicable. The hotspot commission shows up as a separate line on your monthly platform bill alongside the per-subscriber platform fee.

​
Next Steps

Network Provisioning

Deep dive into RADIUS, PPPoE profiles, and bandwidth shaping.

Dunning Automation

Automate payment collection for overdue hotspot and PPPoE subscribers.