Hotspot Self-Service: OTP, Payment & Auto-Suspension

How ISPbills automates hotspot customer self-registration, OTP verification, online payment, RADIUS activation, and auto-suspension — with no staff intervention.

ISPbills turns your MikroTik Hotspot into a fully automated WiFi zone. A customer connects to your SSID, is redirected to the ISPbills captive portal, verifies their mobile number with a 4-digit OTP, selects a package, pays online, and goes live instantly. When their time or data runs out, ISPbills suspends the account automatically.

How It Works — End-to-End Flow

Customer connects to WiFi SSID
        ↓
MikroTik redirects browser to ISPbills captive portal
        ↓
ISPbills checks RADIUS database (mobile number + MAC address)
        ↓
New customer → 4-digit OTP sent via SMS (valid 5 min)
        ↓
OTP verified → trial package assigned → RADIUS user created → internet activated
        ↓
Customer selects package → pays via bKash / Nagad / Shurjopay / etc.
        ↓
ISPbills confirms payment → updates RADIUS attributes → activates session via RouterOS API
        ↓
Session expires or data limit reached → auto-suspended → SMS notification sent
        ↓
Customer revisits portal → purchases new package → reactivated instantly

Prerequisites

Before enabling self-service hotspot:

  • The MikroTik router must be registered in ISPbills with API credentials (api_username, api_password, api_port 8728).
  • At least one Hotspot package must be created with Customer Type = Hotspot.
  • At least one SMS gateway must be configured in Settings → SMS Gateway for OTP delivery.
  • At least one payment gateway must be configured in Settings → Payment Gateways.
  • The Walled Garden must be pushed to the router so unauthenticated customers can reach the payment gateway.

OTP Verification

When a new customer connects for the first time, ISPbills creates a temporary customer record (temp_customer) and sends a 4-digit OTP to their mobile number via the configured SMS gateway.

Property Value
OTP length 4 digits
Validity 5 minutes (cached in Redis)
Delivery channel SMS only (WhatsApp is intentionally disabled for hotspot OTP)
Retry Customer can request a new OTP by revisiting the verification page

After OTP is verified:

  1. ISPbills creates a permanent RADIUS customer with the Trial package.
  2. RADIUS attributes are written to the PostgreSQL database (radcheck and radreply).
  3. ISPbills calls the MikroTik RouterOS API (/ip/hotspot/active/login) to activate internet access immediately.
  4. A welcome SMS is sent to the customer.

The temporary customer record is deleted on successful verification.

The Trial package gives new customers a few minutes of free internet while they browse your available plans. Create a package named Trial with a short validity (e.g. 5 minutes, zero price) to enable this feature.

Supported Payment Gateways

ISPbills supports the following payment gateways for hotspot customer self-payment:

Gateway Region Notes
bKash Tokenized Checkout Bangladesh Recommended — no redirect required
bKash Checkout Bangladesh Classic checkout flow
Nagad Bangladesh Instant payment
Shurjopay Bangladesh Multi-bank support
SSLCommerz Bangladesh Card + mobile banking
Razorpay India Card, UPI, netbanking
Stripe Global Card payments
M-Pesa Kenya / Africa STK push
JazzCash Pakistan
Easypaisa Pakistan
eSewa Nepal
Khalti Nepal
IME Pay Nepal
PayPal Global
HBL Konnect Pakistan
Instamojo India

The Walled Garden push in ISPbills automatically configures Layer7 firewall rules for every enabled payment gateway. See Walled Garden for details.

RADIUS Attributes Written by ISPbills

ISPbills writes to two FreeRADIUS tables for every hotspot customer.

radcheck (authentication rules)

Attribute Value Purpose
Cleartext-Password Device MAC address RADIUS password — matches mac-as-username-and-password mode on MikroTik
Expiration e.g. 07 Jun 2026 23:59:59 Hard time cutoff — FreeRADIUS rejects login after this timestamp

radreply (session policy)

Attribute Example Value Purpose
Mikrotik-Rate-Limit "10M/5M" Download / upload bandwidth cap enforced by RouterOS
Mikrotik-Total-Limit 2147483648 Total bytes (upload + download) allowed — 0 for unlimited

For unlimited data packages, Mikrotik-Total-Limit is set to 0. Session enforcement is then purely time-based via the Expiration attribute.

RADIUS attributes are updated automatically whenever a customer purchases a new package — the new expiry and limits are written in real time, and the MikroTik session is refreshed via the RouterOS API.

RouterOS API — How ISPbills Activates Sessions

ISPbills uses the MikroTik RouterOS API (port 8728) to perform two operations:

Login (activate internet access)

After OTP verification or payment confirmation, ISPbills calls:

Command: /ip/hotspot/active/login
Parameters:
  ip          → customer's current IP address
  mac-address → customer's device MAC address
  user        → customer's RADIUS username (MAC address)
  password    → customer's RADIUS password (MAC address)

This activates the session immediately — the customer does not need to refresh their browser or reconnect.

Logout (terminate session)

When a customer is suspended or logs out from the portal, ISPbills calls:

Command: /ip/hotspot/active (getMktRows filtered by user, then removeMktRows)
Effect:  Removes the active session from the MikroTik hotspot active table

The RouterOS API credentials (api_username, api_password, api_port) must be correct in the router settings or session activation will fail silently. Verify them in Routers & Packages → Routers → Edit.

Returning Customers — MAC Re-Authentication

ISPbills stores the device MAC address as the RADIUS username. On subsequent visits:

  • Active package — ISPbills returns Access-Accept with fresh RADIUS attributes. The RouterOS API login call fires automatically — the customer goes online without entering anything.
  • Expired / suspended — ISPbills returns Access-Reject. MikroTik redirects the customer to the portal to purchase a new package.
  • New device, same mobile number — ISPbills detects the MAC change and initiates a MAC replacement flow so the customer can link their new device to their existing account.

Multi-AP deployments: All access points in the same hotspot zone must broadcast the same SSID. ISPbills identifies customers by MAC address — a different SSID is treated as a different network and MAC re-auth fails.

Auto-Suspension

ISPbills runs a scheduled command (auto:suspend_customers) that checks all hotspot customers against their package limits. Two conditions trigger suspension:

Data limit exceeded

ISPbills sums the RADIUS accounting bytes (upload + download) for the customer from the radacct table and compares against the package's total_octet_limit. If the limit is breached:

  • customer.status → suspended
  • customer.suspend_reason → volume_limit_exceeds
  • Event logged to hotspot_logs and auto_suspension_logs

Time limit exceeded

ISPbills compares package_expired_at against the current time in the operator's timezone. If the package has expired:

  • customer.status → suspended
  • customer.suspend_reason → time_limit_exceeds
  • Event logged to hotspot_logs and auto_suspension_logs

What happens to the customer

On the customer's next connection attempt, ISPbills sends an SMS notifying them that their balance is low (sent once per suspension cycle). The customer is redirected to the portal to purchase a new package.

RouterOS also enforces limits natively via the Expiration and Mikrotik-Total-Limit RADIUS attributes — sessions are terminated at the network level even if the ISPbills scheduler has not yet run.

Suspension events are viewable in the ISPbills dashboard under Logs → Hotspot.

Operator Recharge from Dashboard

Operators can manually recharge or change a hotspot customer's package from the dashboard — for cash walk-in customers or support scenarios.

  1. Navigate to Customers and find the customer.
  2. Use Actions → Hotspot Recharge or Actions → Change Package.
  3. ISPbills shows available hotspot packages (filtered by connection_type = Hotspot) with a real-time invoice preview.
  4. After confirming, ISPbills:
    • Records the payment as Cash
    • Updates the customer's RADIUS attributes
    • Activates the session via the RouterOS API immediately
    • Logs the recharge to hotspot_logs and pgsql_activity_log

A PDF voucher/receipt is generated for every payment (self-service or operator-assisted). Download it from Accounts → Customer Payments → Download Voucher.

Hotspot Logs

ISPbills records all hotspot events in the hotspot_logs table. View them in the dashboard under Logs → Hotspot.

Action Description
registration_attempt A new customer started the OTP flow
login A returning customer was successfully authenticated
mac_replace_attempt Customer tried to connect from a new device
recharge Operator manually recharged the customer

Troubleshooting

Customer stuck on captive portal after payment

Verify the MikroTik API credentials in Routers & Packages → Routers → Edit. ISPbills must be able to connect to the router on port 8728. Check Logs → Hotspot for login errors.

Payment page is blank or won't load

The Walled Garden is missing or incomplete. Run Push to Router again from Routers → Actions → Walled Garden. Re-run whenever you enable a new payment gateway.

OTP not received

Check Logs → SMS History in ISPbills. Verify the SMS gateway has sufficient balance and the correct credentials in Settings → SMS Gateway.

Customer not suspended after data limit is reached

Confirm radius-interim-update is set in the MikroTik hotspot profile (e.g. 2m). Without accounting updates, ISPbills cannot track consumption against the Mikrotik-Total-Limit.

MAC re-authentication not working

All access points in the zone must use the same SSID. Check this in MikroTik under Wireless → Interfaces and confirm the SSID is identical on every AP.