WISPOX setup and operating guide.

Overview

WISPOX is an ISP operations platform for MikroTik hotspot and PPPoE networks. It helps a service provider manage routers, customer accounts, vouchers, packages, SMS and WhatsApp notices, payments, reports, staff access, support tickets, and ISP workspaces.

The app has four main surfaces. The public website explains the product and sends users to login or registration. The ISP dashboard is the private workspace used by owners and staff. The customer portal lets customers buy access, redeem vouchers, manage accounts, and request support. The platform area lets WISPOX admins manage tenants, billing plans, subscription payments, domains, and support sessions.

Current Feature Map

Use this section as a reference for the major modules currently available in WISPOX.

Workspace Setup

A new ISP starts from the Register page. The form creates a workspace on wispox.com and records the ISP name, workspace slug, admin name, phone, email, selected plan, billing cycle, and password.

Steps

1. Open /register.
2. Enter the business name and workspace slug.
3. Enter the admin contact details.
4. Select a subscription plan and billing cycle, or arrive from a public pricing card with the plan and cycle already selected.
5. Submit the form, verify the OTP sent by SMS/email, and sign in from /login.

Subscription plans

Active public plans are read from the platform database, not hardcoded on the website. Current active plans are Wispox Starter, Wispox Growth, and Wispox Business. The public pricing page shows monthly prices and dynamically calculates yearly prices as monthly price × 10, giving the customer 2 months free.

When a visitor clicks a pricing card, WISPOX passes both values to signup, for example /register?plan=wispox-starter&interval=yearly. The selected plan and billing cycle are kept through OTP verification and attached to the workspace subscription record.

Router Setup

The router wizard guides staff through MikroTik setup. A step cannot be skipped until the required fields are complete.

Required router details

• Router name
• Connection type
• Management IP for public IP routers
• API username
• API password
• API port, usually 8728

RouterOS services

For public IP routers, RouterOS API must be reachable from the WISPOX server. The MikroTik hotspot profile must use RADIUS, and the RADIUS client must point to the WISPOX server or tunnel address.

Router onboarding and audits

WISPOX can generate router onboarding scripts and tokens so field staff can connect a router to the correct workspace. Router setup audits record important setup actions, which helps owners confirm what was configured and when.

Hotspot reconnect — cookie login

The WISPOX setup script configures the hotspot profile with login-by=cookie,http-chap,http-pap. Cookie login means that after a customer authenticates with their username and password, MikroTik sets a browser cookie and uses it to reconnect them automatically on return visits — without needing the password again, and without relying on the device's MAC address.

This is the correct reconnect method for modern devices. Android, iOS, and Windows randomise the MAC address per network, so MAC-based reconnect fails when the MAC changes between sessions. Cookie login is unaffected by MAC randomisation.

Updating existing routers

Routers set up before August 2026 may still have login-by=mac in their hotspot profile. Run this command once from the router terminal or the WISPOX remote console to switch them over:

/ip hotspot profile set [find name=wispox-hsprof] login-by=cookie,http-chap,http-pap

Customers already connected are not affected. The change applies to the next reconnect attempt.

WireGuard Path

WireGuard is used when the router site has a shared IP address or no inbound port forwarding. The router dials out to the WISPOX server, then WISPOX reaches the router through the tunnel address.

Information needed

• Router tunnel address
• Server endpoint
• Allowed address
• Server public key
• Router public key

Basic flow

1. Create the WireGuard interface on MikroTik.
2. Add the peer using the server public key.
3. Add the tunnel IP address to the router.
4. Allow API traffic over the tunnel only.
5. Use the router wizard to save and test the tunnel path.

Monitoring and Outages

WISPOX includes router health monitoring for operational visibility. Health snapshots, interface snapshots, router metrics, and session cache data help the dashboard show whether routers are reachable and whether customers are actively connected.

Router alerts

• Router live monitoring can be enabled from platform settings.
• Admin notifications highlight router issues that need attention.
• Router alerts can be sent by SMS when support staff need to act quickly.

Service outages

Service outages track downtime for a router or site. When an outage is reviewed, WISPOX can apply service credits to affected customers by extending their expiry time by the outage duration.

Customers

Customer records store usernames, passwords, package details, phone numbers, account status, expiry date, service type, router context, and captured device information. Staff can create customers by form, sell a package, suspend a user, activate a user, extend expiry, or move a package to a supported device flow.

Customer statuses

• Active: The account can use the hotspot service.
• Expired: The paid period has ended.
• Suspended: Staff have blocked the account.

Active sessions come from RADIUS records and router session cache. If sessions do not show, check router accounting, RADIUS secret, tunnel reachability, and the session polling job.

Customer communication

WISPOX can send customer credentials, payment confirmations, expiry reminders, outage credit notices, and support replies by SMS or email depending on the workspace settings.

Packages and Sales

Packages define the internet access product sold to customers. Typical plans include hourly, daily, weekly, and monthly access. Packages can include price, validity, speed profile, data limit, device limit, session timeout, router context, and whether the validity starts immediately or on first login.

Vouchers

Vouchers are pre-generated access codes. Staff can print them, export them, assign them to agents, and track sales.

Voucher agents

Agents receive voucher stock and sell to customers outside the office. The admin agent page tracks stock, payouts, commission rate, and transaction history. The agent portal gives agents a simpler OTP-protected login where they can view and print assigned voucher stock.

Payments

WISPOX tracks customer payments, ISP subscription payments, manual payments, invoices, and receipts. Paystack and Hubtel handle online customer package payments where enabled. Paystack also handles WISPOX workspace subscription payments and auto-renew plans.

Workspace subscription billing

• Monthly billing charges the plan's current monthly price.
• Yearly billing charges monthly price × 10 and grants 12 months of access.
• Paystack auto-renew creates a monthly or yearly Paystack plan object for the selected WISPOX plan.
• Platform admins can sync billing plans to Paystack when prices or names change.
• The Paystack sync screen reconciles local subscription payment records against Paystack transaction history.

Payment checks

• Confirm the Paystack public key and secret key.
• Confirm the callback URL in Paystack.
• Check the payment reference on the report page.
• Use SMS alerts to notify ISPs after package payment.

Customer Portal

The customer portal is the customer-facing side of a workspace. It can be branded with the ISP logo, colour, support note, and portal footer settings.

Portal actions

• Buy hotspot packages online through the enabled gateway.
• Buy PPPoE/home broadband packages where supported.
• Redeem vouchers.
• View package status and receipts.
• Create support tickets.
• Reconnect through the MikroTik captive portal flow.

Accounting

The accounting module helps an ISP track money beyond raw payment records. Online payments can be credited to configured accounts, while staff can record income entries, expenses, transfers, recurring expenses, and budgets.

Accounting tools

• Accounts with opening balances and date-filtered activity.
• Income entries for non-gateway income.
• Expense entries for operations costs.
• Account transfers for moving funds between accounts.
• Monthly budgets by category.
• Recurring expenses with next-due tracking.
• Agent commission payouts linked to expense records.

Reports

Reports help owners review performance without opening many pages. The dashboard shows active sessions, customer counts, router count, today revenue, total revenue, pending payments, voucher status, new customers, expiring customers, onboarding progress, and recent activity.

Common reports

• Payments report
• Subscription report
• Customer export
• Voucher export
• Accounting report
• Audit log
• Agent performance
• Router traffic and health snapshots
• Subscription payment exports

Insights

The insights screen uses workspace activity to surface practical business prompts, including churn risk, expiry patterns, package performance, agent performance, and payment trends.

Domains

Workspaces can run on the main WISPOX domain or a custom domain. Custom domain requests are submitted by the ISP, verified with a DNS token, then reviewed by the platform admin.

Wildcard DNS

For workspace subdomains, create a wildcard DNS record that points *.wispox.com to the WISPOX server. The app can then serve registered workspace slugs without a manual DNS record for each ISP.

Custom domain approval

1. The ISP submits the domain request.
2. The platform admin reviews it.
3. DNS is pointed to the server.
4. The platform admin verifies and approves the domain.
5. The certificate broker queues the virtual host and TLS certificate request.

Security

WISPOX includes staff permissions, login alerts, email verification, password reset, two-factor verification, account lockout after failed login attempts, session timeout, audit logs, support-session tracking, and secure cookie settings.

Recommended settings

• Turn on two-factor verification for platform admins.
• Use staff permissions for non-owner users.
• Keep router API access limited by firewall or WireGuard.
• Review audit logs after staff or billing changes.
• Use HTTPS for all domains and portals.
• Use the support-session banner when platform staff impersonate a workspace admin for setup help.

MAC address handling

WISPOX records a customer's device MAC address when it is captured from the MikroTik captive portal redirect. This is stored on the customer record for support and analytics purposes.

WISPOX does not write RADIUS entries keyed by MAC address. Earlier versions did — using the MAC as both the RADIUS username and password — which was a security risk because MAC addresses are broadcast in plaintext and can be read by any device on the same network. A bad actor who observed a connected customer's MAC could use it to authenticate without a voucher or password.

Reconnect is instead handled by MikroTik's cookie login (login-by=cookie), which is browser-session-based and not tied to the hardware address. This also means the platform works correctly with devices that randomise their MAC address per network, which includes Android 10+, iOS 14+, and Windows 11.

Hotspot credential security

• Enable HTTPS on the MikroTik captive portal so credentials are not transmitted in plaintext over the local network.
• Keep Simultaneous-Use limits on packages to prevent credential sharing.
• SMS credentials are sent once at activation. Customers can retrieve them from the self-service portal.

Platform Administration

Platform administration is reserved for WISPOX operators. It controls tenants, subscription plans, subscription payment reports, Paystack plan sync, platform notification settings, custom domain approval, metrics, exports, and support sessions.

Billing plans

Plans are stored in saas_plans. Each plan has a code, name, monthly price, router limit, customer limit, staff limit, voucher limit, active flag, sort order, and feature JSON. Public pricing, signup, tenant limits, billing, and Paystack sync all read from these plan records.

Tenant operations

• Activate or suspend workspaces.
• Change a tenant's plan manually.
• Credit extra days after support review.
• Export tenant data.
• Start and end support impersonation sessions.
• Approve, unapprove, or retry custom-domain certificate requests.

Platform metrics

The metrics view summarises monthly recurring revenue, annualised recurring revenue, active and suspended tenants, churn, trials ending soon, signups by month, revenue by month, new subscriptions, totals by plan, and top tenants by customer count.

Troubleshooting

Hotspot users cannot log in

• Check the MikroTik RADIUS client secret.
• Check that the hotspot profile has use-radius=yes.
• Check that RADIUS accounting is turned on.
• Check that RouterOS can reach the WISPOX server or WireGuard tunnel address.

Active sessions do not show

• Check RADIUS accounting port 1813.
• Check that interim accounting updates are enabled.
• Check the router session polling job.
• Check that WISPOX can reach the router API.

Paystack payment hangs

• Check API keys.
• Check webhook and callback URLs.
• Check the payment reference in the subscriptions report.
• Check SMS settings before expecting payment SMS notices.

Yearly subscription amount is wrong

• Check the plan's current monthly_price in Platform > Billing Plans.
• Yearly price is calculated as monthly_price × 10; do not edit the public website manually.
• After changing a plan price, run Platform > Billing Plans > Sync to Paystack so recurring Paystack plans match WISPOX.
• Existing completed payments keep their recorded amount. New checkouts use the current plan price.

Support tickets do not notify staff

• Check notification settings and support contact settings.
• Check SMS and email credentials in the workspace or platform settings.
• Check the notifications page for unread support items.

Customers cannot reconnect after MAC address change

Android, iOS, and Windows randomise the MAC address per network by default. If a customer's router still has login-by=mac in the hotspot profile, they will be prompted to log in again every time their MAC changes — which can be every session on modern devices.

Run this one-liner from the router terminal or the WISPOX remote console to switch to cookie-based reconnect:

/ip hotspot profile set [find name=wispox-hsprof] login-by=cookie,http-chap,http-pap

Routers provisioned after August 2026 using the WISPOX setup script already have this setting; only older routers need the update.

Customers are prompted to log in on every new browser or device

Cookie login stores a session cookie in the browser. If the customer clears cookies, switches to a new browser, or opens the portal on a different device, they will be prompted to log in again with their username and password. This is expected behaviour — the cookie is per browser, not per device. Customers can retrieve their credentials from the self-service portal at any time.