What is a captive portal?

What a captive portal is

A captive portal is a web page that intercepts a user's first connection to a network and requires them to take an action — log in, accept terms, enter a code, or pay — before granting internet access. DataRadius is ISP billing and management software that includes a branded captive portal with built-in payment collection and voucher support.

Connect to Wi-Fi at an airport, a hotel, a restaurant, or a public park, and the page that appears asking you to log in or agree to terms is a captive portal. For an ISP or hotspot operator, it is the front door to a paid service: it turns an open Wi-Fi signal into a controlled access point where every session is authenticated and, optionally, monetized.

Captive portals serve three functions for operators:

1. Access control. Only authenticated users get internet access. Everyone else sees the portal page.
2. Compliance. Accepting terms of service creates a record that the user agreed to acceptable use policies — a legal requirement in many jurisdictions for public Wi-Fi.
3. Revenue collection. When integrated with a payment system, the portal becomes a point of sale where subscribers buy access plans and pay directly from their phone.

The portal itself is a standard web page — HTML, CSS, and JavaScript served over HTTP. What makes it "captive" is the network behavior behind it: the router blocks all internet traffic for unauthenticated devices and redirects their web requests to the portal page.

How the redirect works

The router intercepts traffic from unauthenticated devices and forces their browser to load the portal page — this redirect is what makes the portal "captive."

The technical mechanism combines DNS interception, HTTP redirection, and a concept called a walled garden. Here is the sequence:

1. Device connects to Wi-Fi. The subscriber's phone or laptop associates with the SSID and receives an IP address via DHCP. At this point, the device has a local network connection but no internet access.

2. Traffic is blocked. The router's firewall blocks all outbound traffic from the device except DNS queries and connections to addresses in the walled garden — a whitelist of domains and IPs that unauthenticated users are allowed to reach. The walled garden includes the captive portal server and any payment provider endpoints needed to complete a transaction.

3. DNS interception. When the device tries to resolve any domain (for example, example.com), the router intercepts the DNS query and returns the IP address of the captive portal server instead of the real address. The device's browser connects to the portal server thinking it is reaching example.com.

4. HTTP redirect. The portal server responds with an HTTP 302 redirect to the actual portal URL. The browser follows the redirect and loads the portal page.

5. Captive portal detection. Modern operating systems (iOS, Android, Windows, macOS) actively probe for captive portals. When the device connects to Wi-Fi, the OS sends an HTTP request to a known URL (for example, Apple uses captive.apple.com/hotspot-detect.html). If the response is not what the OS expects, it concludes a captive portal is present and opens the portal page — either in a pop-up browser window or as a notification.

6. Authentication. The subscriber interacts with the portal — enters credentials, selects a plan, makes a payment. The portal server communicates the authentication result to the router.

7. Access granted. The router removes the device from the blocked list and allows full internet traffic. The walled garden and DNS interception no longer apply to this device. The subscriber is online.

RFC 7710 formalized how routers can signal the presence of a captive portal through DHCP options and IPv6 Router Advertisements, giving operating systems a standards-based way to detect portals. RFC 8908 extended this with a Captive Portal API — a JSON endpoint the device queries to learn the portal URL, whether the user is authenticated, and how much time or data they have remaining.

Authentication methods

The authentication method determines what the subscriber does on the portal page before getting online — and the right choice depends on who your subscribers are and how they pay.

Voucher codes. The subscriber enters a code printed on a physical card or received digitally. The portal validates the code against the billing system and activates the corresponding plan. Vouchers work well for cash-based economies and situations where subscribers buy access from an agent or kiosk. No phone number or personal information is required. Downsides: voucher distribution requires logistics (printing, stocking, agent management), and unused vouchers represent unredeemed revenue.

SMS verification. The subscriber enters their phone number, receives a one-time code via SMS, and enters it on the portal. This confirms the phone number and creates a subscriber record. SMS verification is simple for the subscriber and gives the operator a contact channel for future communication (renewal reminders, promotions). It requires an SMS gateway integration and incurs a per-message cost — typically $0.01–$0.05 depending on the country and provider.

Social login. The subscriber authenticates using an existing account — Google, Facebook, or Apple. This eliminates the need to create new credentials and collects the subscriber's name and email (with their consent). Social login reduces friction but introduces a dependency on third-party APIs and may not work reliably on the limited browser windows that some mobile operating systems use for captive portals.

Username and password. The subscriber creates an account or uses existing credentials. This is common for ISPs that manage recurring subscriptions — the subscriber registers once and logs in on subsequent visits. It requires account management (password resets, profile updates) and adds friction to the first visit.

Direct payment. The subscriber selects a plan, pays (mobile money, card, or other method), and is authenticated automatically upon payment confirmation. No code, no login, no pre-existing account. This is the lowest-friction option for operators selling access to walk-in users.

MAC-based auto-login. After the first authentication, the subscriber's device MAC address is remembered. On subsequent visits, the device is recognized and granted access without showing the portal again (as long as the plan is still active). This improves the repeat experience but can be unreliable because some devices randomize MAC addresses for privacy.

Payment integration

Integrating payment directly into the captive portal turns a Wi-Fi network into a self-service revenue channel that collects money 24 hours a day without staff.

The payment flow in a captive portal works like this:

1. The subscriber connects to Wi-Fi and sees the portal.
2. The portal displays available plans — each with a name, duration, speed, data allowance, and price.
3. The subscriber selects a plan and chooses a payment method.
4. The portal initiates the payment: sends a mobile money prompt to the subscriber's phone, opens a card payment form, or accepts a voucher code.
5. The payment provider confirms the transaction via a callback to the billing system.
6. The billing system creates subscriber credentials on the router (a hotspot user with the plan's speed and duration).
7. The portal detects the activation and redirects the subscriber to the open internet.

Mobile money is the dominant payment method for hotspot portals in Africa and parts of Asia. The integration works through the mobile money provider's API: the portal sends a payment request, the provider prompts the subscriber's phone, the subscriber confirms with a PIN, and the provider sends a callback. The entire flow takes 10–30 seconds.

Card payments work through standard payment gateways. The portal embeds a payment form (or redirects to the gateway's hosted page), the subscriber enters card details, and the gateway processes the charge. Card payments are common in markets with high card penetration but add PCI compliance requirements.

Vouchers are technically a payment method too — the code represents prepaid value. The subscriber enters the code on the portal, the billing system validates and consumes it, and access is granted. No external payment API is needed.

Key implementation detail: the payment confirmation callback and the subscriber activation must be atomic. If the payment succeeds but activation fails (router unreachable, timeout, bug), the subscriber has paid for nothing. Build retry logic and a reconciliation process for this case. The billing system should queue activations and retry until the router confirms the session is created.

Portal design that converts

A well-designed portal converts more visitors into paying subscribers — and the primary design principle is speed, not aesthetics.

The subscriber is standing in a coffee shop, a bus station, or a lobby. They connected to Wi-Fi because they need internet right now. Every second the portal takes to load, every extra tap required, and every confusing element reduces the chance they complete the process.

Load time matters more than anything else. The portal loads over a network where the subscriber has no internet access — it is served through the walled garden, often on a link shared with dozens of other users. Target under 3 seconds on a congested connection. Minimize assets: compress images, inline critical CSS, avoid JavaScript frameworks that add hundreds of kilobytes. A portal that loads in 1 second on a fast link and 5 seconds on a slow one will lose subscribers on the slow link.

Show plans immediately. The first thing the subscriber should see is what they can buy and how much it costs. No splash screens, no brand videos, no scrolling past marketing copy. Plans displayed as a simple list or grid: name, duration, price. Three to five plans cover most needs.

Minimize input fields. Every field the subscriber must fill in is a point where they might abandon the process. For a payment-based portal, the only required input is the payment method (and often just their phone number for a mobile money prompt). Name, email, and other profile fields can be collected later or not at all.

Branding belongs in the background. A logo and your business name establish identity. Beyond that, visual design should serve clarity — high contrast text, large tap targets (minimum 44×44 pixels per Apple's Human Interface Guidelines), and readable font sizes (16 px minimum on mobile to prevent auto-zoom).

Mobile-first layout. Over 80% of captive portal traffic comes from phones. Design for a 360-pixel-wide screen first. Test on actual devices — not just browser emulators — because captive portal browser windows on iOS and Android behave differently from full browsers. Some do not support JavaScript redirects. Some do not persist cookies. Design for the least capable browser window your subscribers will encounter.

Show confirmation. After payment, display a clear confirmation message with a receipt reference before redirecting to the internet. Subscribers who are unsure whether payment worked will contact support or try to pay again — both are costly.

Common pitfalls and how to avoid them

Captive portals interact with constantly evolving device operating systems, browser security policies, and network conditions — several common issues trip up operators repeatedly.

HTTPS interception failures

Modern browsers enforce HTTPS strictly. When a subscriber tries to visit https://example.com and the router redirects them to the captive portal, the browser sees a certificate mismatch (the portal's certificate does not match example.com) and shows a security warning instead of the portal. The subscriber sees an error page, not your login screen.

Mitigation. Do not rely on HTTPS interception. Instead, rely on two mechanisms that work reliably:

1. Captive portal detection probes. Every major operating system sends HTTP (not HTTPS) probe requests to detect captive portals. Let these probes hit your portal redirect. The OS then presents the portal in its dedicated browser window.
2. DNS-based redirection. For HTTP requests, DNS interception works cleanly — return the portal's IP for any domain query from an unauthenticated device.

Configure your walled garden to include the captive portal detection domains for all major operating systems: captive.apple.com, connectivitycheck.gstatic.com, www.msftconnecttest.com, and detectportal.firefox.com. If these domains are blocked, the OS cannot detect the portal and the subscriber sees no prompt at all.

Mobile captive portal browser limitations

iOS and Android open captive portals in a special mini-browser — CNA (Captive Network Assistant) on Apple, a similar component on Android. These mini-browsers have limitations:

• No access to cookies from the main browser. Sessions established in the mini-browser do not persist to Safari or Chrome.
• Limited JavaScript support. Complex payment form logic may fail.
• Automatic dismissal. On some OS versions, the mini-browser closes automatically after detecting that internet access is available, potentially interrupting a payment flow.

Mitigation. Keep the portal interaction minimal and completable within the mini-browser. After authentication, redirect to a simple success page. If you need the subscriber to do something in their full browser (account management, receipts), provide a link they can open manually.

Slow portals on congested networks

When your access point serves 30 subscribers sharing a 10 Mbps uplink, a new subscriber trying to load the portal competes for bandwidth with everyone else's traffic. A 500 KB portal page may take 10 seconds to load, by which time the subscriber has given up.

Mitigation. Optimize the portal for size — target under 100 KB total including all assets. Use QoS rules on the router to prioritize portal and payment traffic for unauthenticated devices. Some operators serve a lightweight fallback page (plan list and payment form only, no branding assets) that loads under 20 KB, and race it against the full branded page — whichever arrives first is what the subscriber sees.

MAC randomization breaking return sessions

Since iOS 14 and Android 10, devices randomize their Wi-Fi MAC address by default — using a different address for each network, and sometimes rotating it periodically. If your portal uses MAC addresses to identify returning subscribers, they appear as new users every time.

Mitigation. Do not rely solely on MAC addresses for subscriber identification. Use account-based authentication (phone number, email, or stored credentials) for returning subscribers. If MAC-based auto-login is a feature, inform subscribers that they may need to log in again if their device uses a private address, and provide a link to relevant device settings.

Walled garden misconfigurations

If the walled garden does not include all the domains and IPs needed for the portal and payment flow, critical requests fail silently. The portal might load but the payment form cannot reach the payment provider's API. Or the portal loads partially — CSS and images blocked, leaving an unstyled mess.

Mitigation. Test the full flow from an unauthenticated device after every configuration change. Verify that the walled garden includes: the captive portal server domain, the payment provider's API domains, any CDN domains serving portal assets, and the OS captive portal detection domains listed above. Use the router's traffic log to identify blocked requests from unauthenticated devices.