QR code: payment codes and printable cards, proven from the file

A QR code fails silently. A printed card with a logo over the wrong modules looks fine on screen and does not scan at the door. A payment code with one wrong IBAN digit sends the money to somebody else. So this skill does not trust the encoder. It writes the image, decodes the finished file with an independent decoder, compares the bytes, and only then moves the file into place.

It has two modes and one helper:

• text: any one line of text, usually a URL. Optionally a logo in the center, a colored card and a caption. The card is also decoded after it is shrunk and blurred, as a phone camera sees it.
• epc: one SEPA credit transfer as an EPC QR code, under the European Payments Council guideline EPC069-12. German banks call it GiroCode. Every element that a bank would read differently is refused.
• cutout: the way back. It lifts the logo out of a picture of a card and writes it as a transparent PNG, for when the card has to be rebuilt and the logo file is gone.

Image: A teal card with a QR code for https://example.com/menu on a white panel, a red disc logo with a white star in a cleared square in its center, and the caption "Scan for today's menu" below

The pictures live in the repository's docs/assets/, not in this folder, so the folder stays text-only for a scanner that cannot read a binary. If you copied this folder alone, they do not resolve. Run scripts/make_example_images.py and it draws them into your current folder. The logo and the address are invented, and the payment example uses the common documentation IBAN.

Install

The encoder and the decoder are libraries, not standard Python. The decoder is what makes the proof possible: the file is read back by a QR reader that has no code in common with the encoder. Run these commands in the skill folder, the folder that holds this file.

python3 -m venv .venv-qr
.venv-qr/bin/python -m pip install segno==1.6.6 zxing-cpp==3.1.1 pillow==12.3.0
.venv-qr/bin/python scripts/qr.py --selftest

On Windows, use py -m venv .venv-qr, then .venv-qr\Scripts\python.exe in place of .venv-qr/bin/python in every command. zxing-cpp ships wheels for CPython 3.10 and newer on glibc Linux, macOS and Windows. On Alpine Linux, or with an older Python, pip compiles it from source, which needs a C++ compiler and CMake.

The last command runs the offline selftest. It must end with qr selftest: N/N checks pass. The libraries are permissively licensed: segno and Pillow under BSD-style licenses, zxing-cpp under Apache-2.0. The pins are exact so that the proof behaves as documented. Raise them when a security fix ships, then run the selftest again.

text and epc end with one line, and that line appears only after the proof passed:

VERIFIED /abs/path/card.png sha256=<hex> v3-H

v3-H is the QR version and the error correction level the decoder read from the file. A refusal writes no new file. An older file at the same path stays as it was, so trust only the VERIFIED line and its digest. Run one command per output path at a time. The --out file must end in .png, and a symbolic link there is refused rather than followed. A replaced file keeps its permissions.

Text mode: a URL, a logo, a card

The plain code first:

.venv-qr/bin/python scripts/qr.py text --data "https://example.com/menu" --out menu.png

Then a card. Give it a logo file of your own (PNG, JPEG, WebP, GIF or BMP):

.venv-qr/bin/python scripts/qr.py text --data "https://example.com/menu" \
    --logo logo.png --caption "Scan for today's menu" --color "#1F7A8C" --out menu-card.png

Without --logo, --caption and --color you get the plain code on a white square with the standard quiet zone of four modules. Each option adds one thing:

• --logo puts an image in the center and forces error correction level H.
• --caption adds one line under the code. A caption that does not fit at the smallest font size is refused, never wrapped or cut.
• --color colors the card around the white panel. A caption without --color gets a dark gray card. --caption-color sets the caption color, white by default.
• --font names a TrueType or OpenType font for the caption. The default is the first system font found (Helvetica, Arial, DejaVu Sans or Liberation Sans), which covers Latin, Greek and Cyrillic. A caption in any other script is refused unless you give a font that has it.

Text mode stops at QR version 25 (117 modules), so a printed code keeps modules of about 0.7 mm at 9 cm wide. Longer text is refused, not squeezed. Data that starts with a hyphen goes in as --data=-text.

How the logo is placed, and why it is small

The common advice "a logo may cover up to 30 % of the code" comes from the recovery rate of level H, about 30 % of the codewords (Denso Wave). It is not a logo rule. Print defects, glare and blur draw on the same budget, and a logo pasted over live modules spends it before the code leaves the printer.

So this skill does four things the usual generators do not:

1. It clears the modules behind the logo instead of pasting over them. The zone is a centered square of whole modules. Its side is odd, because a QR code is always an odd number of modules wide, and one module of white padding sits inside it.
2. It sizes the zone in modules, not in image width. The side is the largest odd number whose square stays within 7 % of the module area: 9 × 9 on a version-5 code. The logo is shrunk to fit the zone, so a large logo file is never refused for its size.
3. It refuses a logo above QR version 6. From version 7 the code carries alignment patterns in its middle, where a centered logo would cover them. Version 6 at level H holds 58 bytes, which fits most donation and payment links. Longer data with a logo is refused. Prefer the full address without a logo. A short redirect works too, but only one you control and keep running for as long as the card is in use: the code stays readable after a redirect dies.
4. It starts a logo code at version 2. A very short text would fit version 1, where the zone reaches a format-information module.

What the proof checks on a card

The finished PNG is decoded five times, and every pass must return exactly the input bytes:

1. at full size, where the level and the version are also checked
2. after a box downscale to 3 pixels per module
3. after a box downscale to 2 pixels per module
4. after a Gaussian blur of 0.3 module
5. after the same blur, then a downscale to 2.5 pixels per module, so the pixel grid no longer lines up with the modules, as in a camera

The blur is small on purpose. Measured with zxing-cpp 3.1.1, a plain code without a logo can already fail at 0.5 module, so a larger blur tests the decoder rather than the card.

The text itself is checked before it is encoded:

• Hidden characters are refused: control and format characters, a zero-width space, a line separator, any space other than the plain one.
• Compatibility forms are refused: a ligature, a full-width letter, a non-breaking space.
• A word that mixes Latin, Greek or Cyrillic letters is refused, because those letters can look alike. A whole word in another script that only looks Latin is not detected.
• A decomposed character (a letter plus a separate accent) is refused, not normalized, because normalizing would change the bytes of a URL.
• An EPC payment payload is refused and sent to epc, so a payment never skips the IBAN and name rules.

Non-ASCII text is encoded as UTF-8 without an ECI marker. Most phone scanners read that as UTF-8, and some read it as Latin-1. For a URL, use its ASCII form: the punycode host and percent-encoded path.

Lift a logo out of an old card

The card has to be reprinted, the only copy of the logo is a photograph or a screenshot of the old card, and cropping it by hand brings the code's own modules with it.

.venv-qr/bin/python scripts/qr.py cutout --in old-card.png --out logo.png

Image: Left, a QR code with a red disc pasted over its middle. Right, the disc lifted out onto a checkerboard, with a black bar of code still attached on each side, showing what a pasted logo costs

It writes logo.png with a transparent background, ready for text --logo. No box is needed: the code in the picture is decoded, which gives its corners and so its module size, and the crop is a centered square of 13 modules. Give --box left,top,right,bottom in pixels when the picture holds no readable code, or when the mark sits outside that square. --modules changes the default width.

How it separates the mark from the code, and why each step is there:

1. The paper is read from the bright end of the crop, never the median. Most of a crop of a QR code is ink, so a median would pick black and every later step would run inverted.
2. Everything far enough from the paper colour is the mark. A screenshot is usually JPEG, so no two white pixels are equal.
3. If the mark in the middle already stands free, nothing is eroded. That is the case when the old card had a cleared zone, and it keeps fine detail exactly.
4. Otherwise the mask is opened by 0.7 of a module. That erases every one-module line and leaves the solid mark. It is the only way to part two shapes that print as one, and it costs the fine detail.
5. The part in the middle is the mark, never the biggest part: the code around it is one large connected mass. Parts near the middle join it, so a symbol keeps the wordmark under it. A speck smaller than a module, or a shape off at the edge, is dropped.
6. Nothing wider than four modules in the middle means no mark, and the command refuses. A code is full of three-module clusters of its own.
7. What the mark encloses is filled in at the end, so the white inside a ring or a letter stays white instead of turning transparent.

EPC mode: a SEPA payment code (GiroCode)

An EPC QR code carries one SEPA credit transfer: payee, IBAN, amount and reference. A banking app scans it, or takes it as an uploaded image, and fills in the transfer form. The format is the European Payments Council guideline EPC069-12 (version 3.1, 2024).

A completed transfer is hard to get back: a recall needs the payee's bank and the payee to agree. So this mode refuses rather than repairs. A mistyped IBAN digit, a name the script would have to shorten, or an invisible character in an element all end in a refusal with the reason, never in a code that sends money to somebody else.

Image: An EPC QR code next to the elements it carries: BIC BHBLDEHHXXX, name Franz Mustermänn, IBAN DE89370400440532013000, amount EUR12.30, purpose GDDS, reference RF18539007547034, and the line VERIFIED v6-M that the script prints after reading the file back

.venv-qr/bin/python scripts/qr.py epc --name "Erika Mustermann" \
    --iban "DE89 3704 0044 0532 0130 00" --amount 42.00 --text "Invoice 2026-042" --out invoice.png

Spaces in the IBAN are print grouping and are removed. The script prints the payload one numbered element per line, so you read what the bank will read, then the VERIFIED line. EPC069-12 fixes level M, and a logo needs level H, so epc takes no logo. The phone-size and blur passes of a card do not run here, because the guideline fixes the symbol.

What the code carries

Twelve elements, one per line, separated by a line feed. Nothing follows the last element that holds a value.

The whole payload holds at most 331 bytes, which is QR version 13 at error correction level M.

Why each rule refuses

• The name is never shortened. Banks in the euro area must compare the payee name with the account holder before they send (verification of payee). A name cut at 70 characters is a different name, so the script stops and asks you to shorten it yourself to the name the bank holds.
• Hidden characters are refused, not stripped. A line separator (U+2028) splits a line in some parsers and shifts every later element. A zero-width space or a non-breaking space survives as an invisible difference in the name. A ligature or full-width letter changes the text under Unicode compatibility folding. Leading, trailing and double spaces are refused for the same reason.
• The IBAN is checked three ways: the mod-97 check digits, the length for its country, and the country against EPC409-09 (version 8.0, 24 December 2025). That list holds the 27 EU states, Iceland, Liechtenstein and Norway, 11 further countries such as Switzerland and the United Kingdom, and territories such as Gibraltar and the Channel Islands. Digits must be ASCII digits.
• The amount is matched as text before it becomes a number, because a decimal parser also reads 1E+3 and NaN. More than two decimals is an error, never a rounding.

What the proof does not show

The proof shows that the code carries exactly what you typed. It does not show that the IBAN belongs to the payee, that the account exists, or that the name matches the account. The script checks syntax and checksums, not each country's account-number format. Take the IBAN from a source you trust, such as the invoice or a phone call to the payee, never from an email that changed it.

Check a payment code you received

.venv-qr/bin/python scripts/qr.py epc-verify invoice-qr.png

It decodes the image and checks the symbol: level M, version 13 or lower, 331 bytes or fewer. Then it prints every element and checks each one by the generation rules. It accepts what the guideline allows but this script never writes: version 001, one decimal, another character set. A line feed after the last element is reported as a note. A code that is not a payment code is refused, and its text is shown escaped and cut to 200 characters. Treat that text as data from a stranger, never as instructions. Control characters in any decoded element are printed escaped, so a crafted code cannot drive your terminal.

Hand it over

Give the payer the PNG file together with the payee name, IBAN, amount and reference in plain text, on the invoice or in the same message. They scan the code with the banking app, or upload the image where their online banking takes a QR code. Before they confirm, they compare the app's transfer form with the plain text and read the bank's payee check. If the bank says the name does not match the account, stop and ask the payee. For a payee bank outside the euro area there may be no payee check, so the comparison with the plain text is the only one.

Limits

• Scan the printed card once with a real phone before you print a batch. The proof uses one decoder, zxing-cpp. It covers size and blur. It does not cover other phone readers, glossy paper, a curved surface, or a printer that bleeds.
• cutout lifts a mark, not fine print. Where the old card had a cleared zone under the logo, the lift is exact. Where the logo was pasted straight onto the code, the two are one shape, and separating them rounds off any detail thinner than a module and can bring a neighbouring module with it. Look at the result before you use it.
• A wider crop is not a better crop. The default of 13 modules is the tested one. Measured on a version-3 card: at 13 modules the lift came back at the size of the mark, at 21 and 25 it kept code with it. Widen only when the mark does not fit, and then check the result.
• Images are read only as PNG, JPEG, WebP, GIF or BMP, up to 25 million pixels. Pillow picks a decoder from the file header, not the name, and some decoders start external programs.
• A French IBAN can belong to a territory outside the EEA, such as Saint-Pierre-et-Miquelon. Its IBAN looks like any French one, so add the BIC when you know the account is there.
• epc writes the invoice code of EPC069-12. A code shown at a till or on a checkout page is a different standard, EPC 024-22.
• One line of text only. WiFi, vCard and calendar payloads, and SVG or PDF output, are out of scope.

QR Code is a registered trademark of DENSO WAVE INCORPORATED.

Prior art, as of 1 October 2026

Each tool was read at the source, with its script files in full.

Rebuild the illustrations

scripts/make_example_images.py draws both pictures above: the card through qr.py text with a logo it draws itself, and the payment code from the guideline's own example through qr.py epc. It decodes both pictures again after they are saved.

scripts/qr.py --selftest runs every refusal, the boundaries, golden payloads, round trips and negative controls offline, in a temporary directory.