swiss-qr-payment

Generator for the Swiss QR-bill — the payment part and receipt that every Swiss invoice carries since the end of the orange and red payment slips.

The package covers the full standard:

• the Swiss QR Code payload ("Swiss Payments Code") with all 34 elements,

• validation of every rule of the guidelines, each check citing the chapter it enforces,

• the printed slip in PDF, SVG or PNG, in German, French, Italian, English or Romansh.

Normative sources, both published by SIX Interbank Clearing:

The 210 x 105 mm slip as this package renders it, here in German. It is the specimen printed on page 19 of the Style Guide, and the test suite compares the two run by run.

Every millimetre in swiss_qr_payment/layout.py was measured from the 1:1 vector artwork of the Style Guide with tools/measure_styleguide.py, and the test suite compares the rendered slip against that artwork element by element.

Installation

python3 -m venv .venv
.venv/bin/pip install -e .

Runtime dependencies are segno (QR encoding) and reportlab (PDF and font metrics). PNG output additionally needs pymupdf.

The four typefaces the guidelines permit are Arial, Frutiger, Helvetica and Liberation Sans. Liberation Sans is the default: it is metrically compatible with Arial, freely redistributable, and gets embedded into the PDF, so the printout does not depend on the fonts of whoever opens the file.

Related MCP server: pix-mcp

Library

from swiss_qr_payment import Address, QRBill, PrintOptions, generate

bill = QRBill(
    account="CH4431999123000889012",                    # IBAN or QR-IBAN
    creditor=Address(
        name="Max Muster & Söhne",
        street="Musterstrasse",
        building_number="123",
        postal_code="8000",
        town="Seldwyla",
        country="CH",
    ),
    amount="1949.75",                                    # None prints a blank field
    currency="CHF",                                      # CHF or EUR
    debtor=Address(                                      # omit to print a blank field
        name="Simon Muster",
        street="Musterstrasse",
        building_number="1",
        postal_code="8000",
        town="Seldwyla",
        country="CH",
    ),
    reference="210000000003139471430009017",             # QRR, SCOR or nothing
    unstructured_message="Auftrag vom 15.06.2020",
    billing_information="//S1/10/10201409/11/170309/20/14000000/30/106017086",
    alternative_procedures=["eBill/B/simon.muster@example.com"],
)

generate(bill, "bill.pdf", PrintOptions(language="de"))

generate validates the bill first and raises ValidationError if it violates the standard. To inspect the findings instead:

from swiss_qr_payment import validate

for message in validate(bill):
    print(message)      # ERROR reference: ... [IG 2.12.1]

Every settable element

Lines 12–18 (ultimate creditor) are reserved by the standard for future use and are always emitted empty, which is why they are not exposed.

Print options

Command line

swiss-qr-bill \
    --account CH4431999123000889012 \
    --creditor-name "Max Muster & Söhne" \
    --creditor-street Musterstrasse --creditor-building-number 123 \
    --creditor-postal-code 8000 --creditor-town Seldwyla --creditor-country CH \
    --amount 1949.75 --reference 210000000003139471430009017 \
    --language de --output bill.pdf

A bill can also be described by a JSON document, which command line options then override:

swiss-qr-bill --from-json bill.json --amount 99.90 --output bill.svg

Other useful modes:

swiss-qr-bill --from-json bill.json --check-only      # validate, exit 1 on error
swiss-qr-bill --from-json bill.json --print-payload   # dump the QR code content
swiss-qr-bill --make-qr-reference 313947143000901     # append the check digit
swiss-qr-bill --make-creditor-reference 539007547034  # build an RF reference

swiss-qr-bill --help lists every option.

MCP server: letting an agent issue bills

swiss-qr-bill-mcp speaks the Model Context Protocol over stdio, so an agent can produce a payment slip itself:

{
  "mcpServers": {
    "swiss-qr-bill": {
      "command": "swiss-qr-bill-mcp",
      "env": { "SWISS_QR_BILL_OUTPUT_DIR": "/srv/invoices" }
    }
  }
}

Install it with pip install swiss-qr-payment[mcp]. SWISS_QR_BILL_OUTPUT_DIR confines every file the agent writes to one directory and refuses paths that try to leave it; without the variable, paths are resolved against the working directory.

create_bill refuses to write a bill that violates the guidelines and returns the offending rules instead, each quoting its chapter, so the agent can correct the data rather than guess. read_bill closes the loop: after issuing a bill the agent can confirm that a scanner really sees the intended payment data before the file is sent to anyone.

Examples

python3 examples/generate.py

writes the six reference bills of the Style Guide plus a euro bill with a foreign debtor and a "DO NOT USE FOR PAYMENT" notification into examples/out/, in German and English, together with scan-test.pdf, scan-test.svg and scan-test.png for a scanning test.

How the output is verified

Formal verification, not eyeballing. pytest tests/ runs 255 checks:

Against the official artwork. Each of the six example bills printed in the Style Guide is rendered, the resulting PDF is read back (swiss_qr_payment.probe), and every text run is compared with the corresponding run in SIX's own 1:1 artwork — position, baseline, font size and right edge. The line breaks of the structured billing information come out identical to the artwork, character for character.

Against the standard's own data. tools/extract_annex_examples.py parses the six example tables of Annex A of the Implementation Guidelines straight out of the PDF; the payload encoder is checked against those 34 element values. This also reproduces a documented erratum: the Creditor Reference of Annex A example 4 fails its own mod-97-10 check in versions 2.2, 2.3 and 2.4 of the guidelines, and the test asserts that this is detected.

Against a real reader. The slip is rasterised at 200, 300 and 600 dpi and decoded with ZXing, the library behind most mobile banking scanners. The decoded bytes must equal the generated payload exactly, including the largest possible bill and non-ASCII content.

Through a real MCP client. The server is driven over stdio by an actual client session rather than by calling its functions: the schema an agent sees, the transport and the structured results are what is asserted, including that a bill written through create_bill reads back through read_bill with the identical payload, and that the output directory cannot be escaped.

Across the backends. The SVG is rasterised by an independent renderer (rsvg-convert), its symbol is decoded, and the symbol area is compared with the PDF rendering pixel by pixel — it comes out identical, so the two backends cannot drift apart unnoticed.

Known limits of the standard, recorded rather than hidden. Two of them are checked by tests so that they cannot be forgotten:

• The 997 of chapter 6.2 are bytes, not characters. A bill with every element filled to its character limit is 869 bytes in ASCII, 939 bytes with half the message accented, and 1009 bytes when all of it is — the last one does not fit and is rejected.

• At 939 bytes the symbol reaches version 25 with 117 modules, which at the 46 mm mandated by chapter 6.4 gives 0.393 mm per module — below the 0.4 mm minimum of chapter 6.3. The guidelines contradict themselves here, so the validator issues a warning instead of pretending otherwise.

Note on zbar: it cannot read a Swiss QR Code at all. The recognition symbol sits on top of the central alignment pattern; ZXing reconstructs the geometry and repairs the covered modules through the error correction, zbar gives up. tests/test_qr.py::test_zbar_cannot_read_the_recognition_symbol records this and proves the cause by decoding the same symbol without the cross.

Running the tests

The layout tests need the specification PDFs, which are not redistributed here:

python3 tools/fetch_spec.py          # downloads them into spec/
.venv/bin/pip install -e ".[test]"
.venv/bin/python3 -m pytest tests/ -q

Tests that need a document or a library that is missing are skipped, not failed.

Only the PDF embeds the typeface. The SVG names the font family and relies on the viewer having it, so line breaks and ellipses — computed from the real metrics — can look different where the font is missing. Use the PDF whenever the printout matters.

tools/measure_styleguide.py works on any QR-bill PDF, including the output of this package, and prints its geometry in slip-local millimetres — useful for checking a printout against the standard by hand:

python3 tools/measure_styleguide.py bill.pdf 0 --kind text

How this compares to the other Python packages

Two packages already generate Swiss QR-bills in Python. Both are honest work, and both reproduce the same deviations, because both descend from the same Java reference implementation, SwissQRBill by Manuel Bleichenbacher, whose layout constants differ from the Style Guide artwork in places.

Measured with tools/measure_styleguide.py against page 19 of the Style Guide, rendering the specimen printed there:

The point of the table is not that the others are careless: the deviations are inherited, and nothing in those projects would have caught them, because neither compares its output with the source of truth. That comparison is what this package is built around.

Layout reference

Coordinates in millimetres, origin at the top left of the 210 × 105 mm slip.

                    receipt                 payment part
        0        5              57  62    67          113  118           205  210
      0 +--------------------------+-------------------------------------------+
      5 |        Receipt           |    Payment part   |  Account / Payable to |
     12 |  Account / Payable to    |                   |  ...                  |
        |  Reference               | 17 +-----------+  |  Reference            |
        |  Payable by              |    | Swiss QR  |  |  Additional info      |
        |                          |    |   Code    |  |  Payable by           |
        |                          | 63 +-----------+  |                       |
     68 |  Currency   Amount       |    Currency  Amount                       |
     82 |          Acceptance point| 90 ----------------------------------------
        |                          |    Name AV1: ...                          |
    105 +--------------------------+-------------------------------------------+

Licence

MIT. The scissors outline in swiss_qr_payment/drawing.py is taken from the MIT licensed reference implementation SwissQRBill by Manuel Bleichenbacher.