# Swiss QR-bill — quick field reference

This is an implementation-oriented summary of the Swiss Payments Code (SPC) payload used by qrcode4payment. It is **not** a substitute for the official specification; for normative text, refer to:

- *Swiss Implementation Guidelines QR-bill v2.3* (SIX / PaymentStandards.CH).
- *Style Guide QR-bill* for visual/print rules.

## Payload structure

The payload is a single UTF-8 string with **`CR LF`** between fields (parsers also accept plain `LF`). Empty fields are still emitted as empty lines — positional, never omitted.

| #  | Element                 | Field name              | Length / format             | Mand. | Notes |
|---:|-------------------------|-------------------------|-----------------------------|:---:|-------|
| 01 | Header                  | QRType                  | Fixed `SPC`                 | M | Swiss Payments Code |
| 02 | Header                  | Version                 | Fixed `0200`                | M | v2.x |
| 03 | Header                  | Coding Type             | Fixed `1`                   | M | UTF-8 restricted |
| 04 | CdtrInf (Account)       | IBAN                    | 21 chars, `CH` or `LI`      | M | Must be QR-IBAN if reference type = `QRR` |
| 05 | Cdtr                    | AddressType             | `S` or `K`                  | M | Structured / Combined |
| 06 | Cdtr                    | Name                    | 1–70                        | M | |
| 07 | Cdtr                    | StreetOrAddressLine1    | 1–70 (S) / 1–70 (K)         | O | |
| 08 | Cdtr                    | BuildingNoOrAddressLine2| 1–16 (S) / 1–70 (K)         | O | In S: street number; in K: line 2 incl. zip+town |
| 09 | Cdtr                    | PostalCode              | 1–16 (S only)               | M (S) | Empty when AddressType = K |
| 10 | Cdtr                    | Town                    | 1–35 (S only)               | M (S) | Empty when AddressType = K |
| 11 | Cdtr                    | Country                 | 2 chars (ISO 3166-1)        | M | |
| 12 | UltmtCdtr               | AddressType             | `S` / `K` / empty           | O | "For future use" — leave all 7 empty in v2.3 |
| 13 | UltmtCdtr               | Name                    | 0–70                        | O | |
| 14 | UltmtCdtr               | StreetOrAddressLine1    | 0–70                        | O | |
| 15 | UltmtCdtr               | BuildingNoOrAddressLine2| 0–16 / 0–70                 | O | |
| 16 | UltmtCdtr               | PostalCode              | 0–16                        | O | |
| 17 | UltmtCdtr               | Town                    | 0–35                        | O | |
| 18 | UltmtCdtr               | Country                 | 0/2                         | O | |
| 19 | CcyAmt                  | Amount                  | 0.01–999999999.99, dot dec. | O | Empty = open amount |
| 20 | CcyAmt                  | Currency                | `CHF` or `EUR`              | M | |
| 21 | UltmtDbtr               | AddressType             | `S` / `K` / empty           | O | If filled, AddressType is mandatory |
| 22 | UltmtDbtr               | Name                    | 0–70                        | O | |
| 23 | UltmtDbtr               | StreetOrAddressLine1    | 0–70                        | O | |
| 24 | UltmtDbtr               | BuildingNoOrAddressLine2| 0–16 / 0–70                 | O | |
| 25 | UltmtDbtr               | PostalCode              | 0–16                        | O | |
| 26 | UltmtDbtr               | Town                    | 0–35                        | O | |
| 27 | UltmtDbtr               | Country                 | 0/2                         | O | |
| 28 | RmtInf                  | Reference Type          | `QRR` / `SCOR` / `NON`      | M | |
| 29 | RmtInf                  | Reference               | QRR: 27 digits, SCOR: ≤25, NON: empty | C | |
| 30 | AddInf                  | Unstructured message    | 0–140                       | O | Free text for the debtor |
| 31 | AddInf                  | Trailer                 | Fixed `EPD`                 | M | End Payment Data |
| 32 | AddInf                  | Bill information        | 0–140                       | O | Structured B2B info (S1/S2 syntax) |
| 33 | AltPmtInf               | Alternative scheme 1    | 0–100                       | O | |
| 34 | AltPmtInf               | Alternative scheme 2    | 0–100                       | O | |

**Minimum line count:** 32. **Maximum:** 34.

Total payload size after assembly must stay well under the limit; with ECC level M the standard symbol comfortably fits the maximum permitted SPC content.

## Address types

- **S (Structured)** — fields 7–10 carry street, building no, postal code, town separately.
- **K (Combined)** — fields 7–8 carry two address lines that together include street, no, postal code, town. Fields 9–10 must be empty.

The site emits **Structured** addresses by default because they remain readable in older bank apps and avoid edge cases around line breaks.

## Reference rules

| Reference Type | IBAN requirement | Reference field |
|---|---|---|
| `QRR` | Must be a **QR-IBAN** (institution ID 30000–31999) | 27 numeric digits with Modulo-10 recursive check digit at position 27 |
| `SCOR` | Must **not** be a QR-IBAN (regular IBAN) | ISO 11649 Creditor Reference, `RF` + 2-digit check + ≤21 alphanumeric, mod-97-10 |
| `NON`  | Must **not** be a QR-IBAN | Empty |

## QR symbol rules

- Model 2 QR code.
- Error correction level **M**.
- Character encoding: Byte mode, UTF-8.
- Print size: 46 × 46 mm (plus 5 mm quiet zone).
- Centered Swiss-cross overlay: white 7 × 7 mm square; red 6 × 6 mm square inside; white 1.2 mm-wide cross arms spanning 4.2 mm.
- The overlay is *part of* the code as defined by the spec — the reader knows to ignore those modules; that is the reason ECC level M is required.

## Character set

The SPC payload only allows the **Swiss QR-bill Latin character set**:

```
A-Z a-z 0-9
space ! " # % & ' ( ) * + , - . / : ; < > ? @ [ \ ] ^ _ ` { | } ~
À-ÿ subset: ä ö ü Ä Ö Ü à â ä ç é è ê ë î ï ô ö û ü ù ÿ ñ Ñ á ó í ú Á Ó Í Ú ...
```

Anything outside this set should be stripped or replaced before assembling the payload. The site applies a simple sanitizer that drops disallowed characters and warns the user.

## References

- Swiss Implementation Guidelines QR-bill v2.3 — SIX / PaymentStandards.CH.
- ISO 11649 — Financial services — Structured Creditor Reference.
- ISO 13616 — IBAN structure and check digit.
- ISO/IEC 18004 — QR code.