> ## Documentation Index
> Fetch the complete documentation index at: https://docsautomator.co/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Swiss QR-bill

> Add the Swiss QR payment part to your invoices, from the same data that fills your document.

The Swiss QR-bill add-on adds the Swiss payment part, with the QR code that your customers scan in their banking app, to every document an automation creates. The payment part goes on an extra last A4 page, at the bottom as the standard describes, so your template needs no blank space for it.

It works with every template type (Google Docs, Word and PDF) and every way you create documents. You can use it alone or together with the [e-invoice add-on](https://docsautomator.co/docs/features/e-invoices.md). With both add-ons on, one PDF carries the e-invoice data and the QR-bill page.

Before a document is created, DocsAutomator checks the QR-bill against the Swiss QR-bill standard (IBAN, reference check digits, amount, field lengths and allowed characters). When something is wrong, nothing is created or sent, and the run names what to fix.

## Turn on the add-on

1. Open **Settings**, then **Add-ons**.
2. Switch on **Swiss QR-bill**. Only owners and admins can do this.
3. Click **Settings** next to the add-on and enter your seller details.

The add-on is off until you switch it on. Automations without a QR-bill do not change.

### Seller details

The seller details are the account holder on every payment part. They are shared with the e-invoice add-on, so you enter them once.

| Field | Required |
| - | - |
| Legal name, postcode, city | Always |
| Street and number, country | Recommended. An empty country means the country of your IBAN. |
| IBAN | A Swiss or Liechtenstein IBAN (starting with CH or LI), unless you use a QR reference |

### QR-IBAN

A QR-IBAN is a separate account number that your bank gives you with its QR reference service. You need it only for the QR reference type. Enter it under **QR-IBAN** on the same settings page.

## Set up an automation

Open an automation and find its **Swiss QR-bill** section. Fill in the parts below, then switch on **Add a QR-bill**. Most fields suggest a match from your data by name, or from the automation's e-invoice setup.

### Payment

* **Currency:** CHF or EUR.
* **Amount:** the field that holds the invoice total. Leave it empty to let the payer enter the amount, for example for donations. When the automation also creates an e-invoice and the amount is not set, the e-invoice gross total is used.

### Reference

| Reference type | Account | What you map |
| - | - | - |
| No reference | Your IBAN | Nothing. Use the message to identify the payment. |
| Creditor reference (RF) | Your IBAN | Up to 21 letters and digits, for example the invoice number. DocsAutomator adds "RF" and the check digits. A value that already starts with RF is checked as it is. |
| QR reference | Your QR-IBAN | Up to 26 digits, for example the invoice number. DocsAutomator adds leading zeros and the check digit. A 27-digit value is checked as it is. |

The **message** is optional free text of up to 140 characters, for example the invoice number. Your customer sees it in the banking app.

### Payer

The payer's name, street and number, postcode, city and country are optional. Leave them empty to let the payer enter their name and address. When you map any of them, the name, postcode and city are needed. An empty country means Switzerland (CH).

### Language

The payment part uses the language of the automation's locale: German, French, Italian or English. Other locales use English.

## Test document

Create a test document from the section. The result of the checks shows in the section, and nothing is sent. Scan the QR code with your banking app to see what your customer sees. In test mode the QR-bill page carries the test watermark, like the rest of the document.

## Checks and messages

Every check runs before the document is created. When one fails, no file is created, stored or sent, and the run fails with the message `QR-bill not created:` followed by the first problem, plus the number and text of any further problems. In the text below, `...` stands for the value from your data.

### Seller details and account

| Check | Message | Fix |
| - | - | - |
| Legal name, postcode and city are set | `Seller name is empty. Add it in Settings, Add-ons.` (the same for `Seller postcode` and `Seller city`) | Enter the value in the seller details. |
| The IBAN is set (no reference and creditor reference) | `Seller IBAN is empty. Add it in Settings, Add-ons.` | Enter your IBAN. |
| The IBAN checksum is correct | `Seller IBAN "..." is not a valid IBAN.` | Check the IBAN for typos. |
| The IBAN is Swiss or from Liechtenstein | `A QR-bill needs a Swiss or Liechtenstein IBAN (starting with CH or LI).` | Use an account that starts with CH or LI. |
| A QR-IBAN is used only with a QR reference | `Seller IBAN is a QR-IBAN, which works only with a QR reference. Choose QR reference as the reference type.` | Choose QR reference, or enter your normal IBAN. |
| A QR reference has a QR-IBAN | `A QR reference needs a QR-IBAN. Add it in Settings, Add-ons, or choose another reference type.` | Enter the QR-IBAN, or choose another reference type. |
| The QR-IBAN is valid | `QR-IBAN "..." is not a valid QR-IBAN.` | Check it for typos. A QR-IBAN has a bank number from 30000 to 31999 (digits 5 to 9). |
| The seller country is a country | `Seller country "..." is not a country. Use a two-letter code like CH.` | Pick the country again in the seller details. |
| A reference type is chosen | `Reference type is not set.` | Choose a reference type in the automation. |

### Amount and currency

| Check | Message | Fix |
| - | - | - |
| A mapped amount has a value | `Amount is empty.` | Fill the amount field, or remove the mapping to let the payer enter the amount. |
| The amount is a number | `Amount "..." is not a number.` | Map a number field. "1234.50", "1'234.50", "CHF 1234.50" and "1.234,50" are read correctly. |
| The amount is in range | `Amount ... is outside the QR-bill range of 0.01 to 999999999.99.` | Use an amount from 0.01 to 999,999,999.99. Zero and negative amounts are not allowed. |
| The currency is CHF or EUR | `Currency "..." is not allowed. A QR-bill is in CHF or EUR.` | Choose CHF or EUR. A mapped currency field may contain CHF, Fr., EUR or the euro sign. |
| A mapped currency has a value | `Currency is empty.` | Fill the currency field, or use the fixed choice. |

### Reference and message

| Check | Message | Fix |
| - | - | - |
| A reference is mapped and filled (QR reference and creditor reference) | `Reference is empty. The reference type QR reference needs one.` (or `Creditor reference`) | Map the reference field and fill it. |
| The QR reference has the right form | `QR reference "..." is not valid. Use up to 26 digits, or 27 digits with the check digit.` | Map a field with digits only. |
| The QR reference check digit is correct (mod 10, recursive) | `QR reference "..." has a wrong check digit.` | Map the reference without its check digit, or correct it. |
| The creditor reference has the right form | `Creditor reference "..." is not valid. Use up to 21 letters and digits, or a reference starting with RF.` | Remove spaces, dashes and other signs from the value. |
| The creditor reference check digits are correct (ISO 11649) | `Creditor reference "..." has a wrong check digit.` | Map the reference without "RF" and the check digits, or correct them. |
| The message has at most 140 characters | `Message is longer than 140 characters, the QR-bill limit.` | Shorten the message. |

### Payer

| Check | Message | Fix |
| - | - | - |
| A payer has a name, postcode and city | `Payer name is empty. A payer address needs a name, postcode and city.` (the same for `Payer postcode` and `Payer city`) | Fill the fields, or remove all payer mappings. |
| The payer country is a country | `Payer country "..." is not a country. Use a two-letter code like CH.` | Use a two-letter code or a country name such as Schweiz or Switzerland. |

### Every text field

| Check | Message | Fix |
| - | - | - |
| Length limits: names and streets 70, postcodes 16, cities 35 characters | `... is longer than 70 characters, the QR-bill limit.` (with the field name and its limit) | Shorten the value. |
| Allowed characters: Latin letters with their accents, digits, common punctuation and the euro sign | `... contains "...", which a QR-bill does not allow.` | Remove the character, for example a Chinese or Cyrillic letter or an emoji. |
| A field has one value | `... has more than one value. Pick a field with one value.` | Map a field that holds one value, not a lookup with several. |

Line breaks and repeated spaces in your data become one space, so they never fail a check.

### Rare messages

* `The QR-bill could not be built from this data (...).` The data passed our checks but not the library that draws the payment part. Contact support with the message.
* `The QR-bill page cannot be added to this PDF (...).` The finished PDF could not be read, for example a merged PDF that is damaged. Check the merged files, or contact support.

## API and integrations

The QR-bill needs no extra request fields: it reads the fields you map in the automation, also from API, Zapier, Make and n8n requests. A successful response carries `"qrBill": { "ok": true }`, and the PDF at `pdfUrl` has the payment part on its last page. A failed check answers with status 400, the message above and `"code": "QR_BILL_INVALID"`.

## Settings that combine with the QR-bill

* **E-invoice (ZUGFeRD):** the QR-bill page is added first, then the e-invoice data and the PDF/A-3 conversion. One PDF carries both, and it passes the official ZUGFeRD and PDF/A checks with the extra page. With XRechnung, the PDF gets the QR-bill page and the XML file is unchanged. When the amount is not mapped, the e-invoice gross total is used.
* **Merge PDFs:** the QR-bill page is the last page, after the merged PDFs.
* **Signing and acceptance:** the QR-bill page is part of the document your recipient signs or accepts.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.