WiFi QR codes: how to make one that actually connects

WiFi QR codes: how to make one that actually connects

A WiFi QR code is one of the most genuinely useful codes you can hand a client. A guest scans it with their phone camera, taps a banner, and they are on the network: no squinting at a password taped to the wall, no typos, no asking the bartender to repeat it. For a hotel, a cafe, an event or an office reception, it removes a small daily friction dozens of times a day.

It is also one of the most quietly broken codes out there, because the most common generators emit strings that violate the de-facto standard, and almost nobody tests across enough devices to notice. This guide explains exactly what a WiFi QR code is, the precise payload format it uses, the escaping and security-type rules that decide whether it connects, and the one honest limitation that catches agencies out: a WiFi join code cannot be dynamic or tracked. Get these right and your code will connect on the widest possible range of phones.

What a WiFi QR code actually contains

A normal marketing QR code holds a web address. A WiFi QR code is different: it holds a small block of structured text that tells the phone's operating system how to join a network. There is no website involved and no server in the loop. The phone reads the text, recognises the WiFi format, and offers to connect using the details inside.

The format is the WIFI: URI, defined by the ZXing project and now followed by essentially every phone and generator. A minimal example looks like this:

WIFI:T:WPA;S:mynetwork;P:mypass;;

That string says: security type WPA, network name mynetwork, password mypass. The fields are:

• S: is the SSID, the network name. This is required.
• T: is the authentication type. The documented values are WEP, WPA (which covers WPA and WPA2) and nopass for an open network with no password. There is also WPA2-EAP for enterprise networks.
• P: is the password. It is ignored if the type is nopass.
• H: is optional and set to true only for a hidden (non-broadcasting) network.

Two details matter. First, the order of the fields does not matter; T: before S: is fine. Second, the string ends with a double semicolon (;;): one semicolon closes the last field and the second closes the whole URI. Drop the second semicolon and some scanners choke.

The escaping rule that breaks real passwords

This is where hand-made and poorly written codes fall over. If your SSID or password contains any of these characters: backslash, semicolon, comma, colon or double quote, each one must be escaped with a backslash. The ZXing specification is explicit about it.

So a password of My;Pass:2026 is not encoded literally. It becomes:

P:My\;Pass\:2026

If you forget this, the unescaped semicolon in the password is read as the end of the field, the rest of the password is discarded or misparsed, and the connection silently fails with a wrong password. The practical tip: escape backslashes first, then the other characters, otherwise you can double-escape and corrupt the string a different way.

There is one more sharp edge. If your SSID or password happens to look like hexadecimal (for example 1234ABCD), wrap it in double quotes so it is not interpreted as a hex value: S:"1234ABCD". And never let a stray trailing newline sneak into the encoded text. A code generated with a command that appends a newline can fail on both iOS and Android even though the visible characters are correct.

Pick the right security type (the WPA3 trap)

Choosing the wrong authentication type is the single most common reason a WiFi QR code refuses to connect, and modern WiFi has made this trickier than it should be.

The rule is simpler than the generators make it look. For any password-protected home or small-business network (WPA, WPA2 or WPA3 with a pre-shared key), use T:WPA. There is no separate WPA2 value in the standard; WPA covers it. For an open network, use T:nopass or omit the type. Use WEP only for genuinely ancient gear, which you should be replacing anyway.

WPA3 is where it gets messy. The WPA3 specification says that if the type field is present, it should still be set to WPA. But several common tools get this wrong: Android, GNOME and KDE generate T:SAE for WPA3 networks, which is the underlying authentication method, not the value the format expects. A T:SAE code can fail to connect on devices that only understand T:WPA. Windows, by contrast, correctly emits T:WPA. There is a related encoding mismatch too: the WPA3 spec wants special characters percent-encoded, while Android sticks with ZXing-style backslash escaping and does not understand percent-encoding when scanning, so cross-tool WPA3 codes can break.

The safe path for an agency: generate T:WPA for any PSK network, including WPA3, unless you have a specific reason and a tested device set that needs otherwise. If you must support a WPA3-only network and see connection failures, switching the router to mixed WPA2/WPA3 transition mode usually resolves it.

Which phones can scan it

Native WiFi QR scanning has been built into phones for years, so most of your client's customers can use it without installing anything.

• On iPhone, the Camera app has offered to join WiFi from a scanned code since around iOS 11 (2017). Point the camera at the code and tap the "Join network" banner.
• On Android, native WiFi QR support arrived with Android 10, and Settings has a built-in QR scanner next to "Add network" plus a "Share" button that generates a QR for the current network. Many manufacturer cameras (Pixel, Samsung) detect WiFi codes from Android 9.

Treat those version numbers as widely reported community knowledge rather than a formal platform guarantee, because Apple and Google do not publish them as a spec. The important practical point is the fallback: on a device that does not support it, the code is simply read as plain text (WIFI:S:...) and the user has to connect manually. It degrades gracefully, but a confusing wall of text is not the experience you want, so it is worth printing the network name and a short instruction near the code.

The honest limitation: WiFi codes cannot be dynamic or tracked

This is the part agencies most need to hear, because it cuts against how the rest of QR marketing works.

A dynamic, trackable QR code works by encoding a short URL. When someone scans it, their phone visits that URL, your server records the scan and redirects to wherever you currently point it. That indirection is what lets you change the destination after printing and collect scan analytics. We cover the mechanics in dynamic versus static QR codes.

A WiFi join code has none of that, by construction. It is not a URL. It is a local payload that the phone's operating system parses on the device to join a network. There is no server hop, which means:

• You cannot change the WiFi password by editing the code after it is printed. If the password changes, you must generate and reprint a new code. There is no dynamic redirect to update.
• You get no scan analytics. Nothing calls a server, so there is nothing to count. A raw WiFi QR is invisible to your reporting.

There is a clean workaround that gives you the best of both, and it is the pattern we recommend for client work. Use a dynamic, trackable URL code that points to a branded landing page, and put the WiFi details (or an auto-join WiFi code) on that page. Now the page is editable and measurable: you can update credentials, see how many people scanned, and turn the connect moment into a marketing touchpoint with a menu, an offer or an event schedule. The actual WiFi join remains a static local payload, but everything around it becomes dynamic. Pair it with a page built to convert, as covered in QR code CTAs and landing pages that convert.

Security: the password is in plain sight

A WiFi QR code stores the password in plaintext. The code is just text, so anyone who scans it, or who photographs it and runs the image through a free online decoder, can read the SSID and password directly. This is not a flaw to be patched; it is how the format works. The realistic risk is not some remote hack, it is that the credentials are visible to anyone who can see or photograph the code, and that someone could paste a malicious sticker over yours.

Sensible precautions follow from that:

• Put guests on a dedicated guest network with client isolation, so a guest device cannot reach the internal LAN, printers, point-of-sale or file storage.
• Rotate the guest password periodically. Remember that because the code is static, changing the password means reprinting the code; that is the only way to revoke access.
• Do not display the code where people who are not meant to have access can quietly grab it, and check periodically that nobody has stuck a fake over the real one. For the wider threat of tampered and malicious codes, see QR code security for agencies.

If the network captures personal data through a sign-in or captive portal, the usual data-protection rules apply; our GDPR guide covers what that means for QR-driven journeys.

Why a WiFi QR code fails to connect: a checklist

When a code will not connect, work through these in order. Most failures are one of the first three.

1. Wrong security type. An open network marked as WPA, a WPA2 network marked as WEP, or a T:SAE / T:WPA2 value the scanner rejects. Use T:WPA for PSK networks and T:nopass for open ones.
2. Unescaped special characters in the SSID or password (backslash, semicolon, comma, colon, double quote). Escape each with a backslash.
3. A hidden network missing the hidden flag. Set H:true, or some phones will not find the SSID.
4. A stray trailing newline or whitespace in the encoded string. It can break the code on both iOS and Android.
5. A WPA3-only network scanned by an older or WPA2-only device. Switch the router to mixed WPA2/WPA3 mode.
6. A captive-portal network (common in hotels and airports). The code can join the radio, but internet access still needs the user to open a browser and accept terms; a WiFi QR cannot carry that login.
7. A simple password typo or case error when the code was generated. Decode your own finished code and read the password back to confirm it.

If the code will not scan at all, as opposed to scanning but not connecting, that is a different problem; see why a QR code is not scanning.

Where WiFi QR codes earn their keep

The strongest use cases pair convenience with a marketing moment:

• Hospitality: hotel rooms, cafe tables and restaurant menus, where joining the WiFi is the first thing a guest wants to do.
• Events and conferences: on badges and signage, so attendees connect the moment they arrive.
• Offices and co-working: reception and meeting-room guest access without reading passwords aloud.
• Retail: in-store WiFi tied to a promotion or loyalty sign-up.

In every case, the high-value version is not the bare WiFi code stuck to a wall. It is the WiFi join paired with a branded page, so the moment someone connects you have their attention. A vCard contact code follows the same static-payload logic if you also want people to save a contact; see QR code business cards.

Frequently asked questions

How do I create a WiFi QR code?

Use a generator that produces the WIFI: format, and supply three things: the exact network name (SSID), the password, and the correct security type (WPA for almost all password-protected networks). Make sure any special characters in the SSID or password are backslash-escaped, then test the finished code on both an iPhone and an Android phone before printing it.

What is the format of a WiFi QR code?

It is a WIFI: URI, for example WIFI:T:WPA;S:mynetwork;P:mypass;;. S: is the network name, T: is the security type (WPA, WEP, or nopass), P: is the password, and an optional H:true marks a hidden network. The fields can be in any order and the string ends with a double semicolon.

Why won't my WiFi QR code connect?

The usual causes, in order of likelihood: the wrong security type (use T:WPA for WPA, WPA2 and WPA3 pre-shared-key networks), unescaped special characters in the password, a hidden network without H:true, or a stray newline in the encoded string. WPA3-only networks and captive portals (hotels, airports) are common edge cases too.

Can I change the WiFi password without reprinting the QR code?

No. A WiFi QR code is a static local payload, not a redirect, so the password is baked into the code. If the password changes, you must generate and print a new code. To get something editable, point a dynamic URL code at a landing page that shows the credentials, and update the page instead.

Are WiFi QR codes secure?

The connection uses your normal WiFi encryption, but the password itself is stored in the code in plaintext, so anyone who scans or photographs the code can read it. Put guests on an isolated guest network, rotate the password periodically, and watch for tampered or replaced codes. Treat the code as a visible password, because that is what it is.

Does a WiFi QR code work on both iPhone and Android?

Yes, on modern devices. iPhones have supported joining WiFi from the Camera app since around iOS 11, and Android since version 10 (with some manufacturer cameras from Android 9). Older devices read the code as plain text and require manual connection, so it is worth printing the network name alongside the code as a fallback.

Can I track scans of a WiFi QR code?

Not directly. A WiFi join code never contacts a server, so there is nothing to measure. If you need analytics, use a trackable URL code that leads to a page hosting the WiFi details, and measure scans of that page instead.

The short version

A WiFi QR code lets guests join a network by scanning, and it is genuinely useful for hospitality, events, offices and retail. Build it on the WIFI: format, use T:WPA for any pre-shared-key network (including WPA3, despite tools that wrongly emit T:SAE), backslash-escape special characters in the SSID and password, and end the string with a double semicolon. Accept the two real limits: the code is static, so you cannot change the password or track scans without indirecting through a landing page, and the password is stored in plaintext, so use an isolated guest network and rotate it. Above all, test the finished code on both an iPhone and an Android before it goes to print, and pair it with a branded page so a simple connection becomes a marketing moment.