Magic Heidi Swiss QR Invoice API: Prepare Your Integration
Confirm the supported contract and test access before implementing request fields or response formats. QR validation and invoice checks remain part of acceptance testing.
Building invoicing features for the Swiss market? Treat PDF generation, the Swiss QR payment section and payment reconciliation as separate tasks. This page helps define the requirements and acceptance checks for a possible integration.
Estimate implementation effort only after reviewing the contract, data model and test cases.
Confirm Integration Status and Access
Reviewed on 1 November 2026. This page is technical guidance, not an approved public API specification. Before integrating, obtain the currently supported contract, access conditions and an explicitly approved testing method. Contact Magic Heidi with your use case and expected volume.
Earlier versions of this page and the related blog article contained conflicting request and response examples. Those examples are not a reliable basis for production code and are not continued here as a copy-and-paste integration. Confirm field names, date formats, VAT scaling and response structure before use.
This page does not promise a free public test endpoint, a particular authentication method, rate limit, price, SLA or PDF link expiry period. Do not send real customer, patient or bank data to an endpoint without an agreed test environment.
What an Approved API Contract Must Define
| Area | Confirm before implementation |
|---|---|
| Request | Required fields, data types, date format, currency and invoice number |
| VAT | Decimal or percentage representation, rounding, gross/net mode and multiple rates |
| Address | Separate address components, country and validation rules |
| Account and reference | Supported IBAN types, QRR/SCOR/NON, check digits and optional message |
| Response | Actual JSON path to the PDF, status/error format and download permissions |
| Operation | Authentication, limits, timeouts, retries and prevention of duplicate generation |
| Data | Storage location, access, deletion, link validity and your own archive |
Technical Acceptance Tests
- Use only agreed, non-chargeable test calls with synthetic data.
- Check success and validation failures against the actual response. Do not guess field names or error codes.
- Download the PDF and review totals, rounding, language and tax information.
- Decode the QR data and check account, reference, currency and address fields against the current SIX requirements.
- Test invalid IBANs, incompatible account/reference combinations, missing addresses and unsupported currencies. An HTTP success response alone does not prove the invoice is correct.
- Before adding retries, agree how duplicate PDFs and invoice numbers will be prevented. Do not log complete personal invoice data.
Useful Integration Scenarios
An approved generation service can form part of an existing invoicing process, membership system or order workflow. A QR PDF does not receive a payment or prove receipt of funds. Automatic reconciliation also needs suitable bank data and a tested matching process.
Understand QR-IBAN and Normal IBAN
Match the account and reference to your agreed payment workflow.
When to Use a QR-IBAN
Use a QR-IBAN when your agreed payment process uses QRR. The 27-digit QR reference supports identification of payments. Actual reconciliation also requires suitable bank data and software; the generated PDF does not itself mark an invoice as paid.
The QR-IID in positions 5–9 lies between 30000 and 31999. Check the QR-IBAN issued by the institution; do not use an invented example IBAN for testing. Contact your bank about availability, conditions and setup.
When to Use a Normal IBAN
A normal CH/LI IBAN is used with an ISO 11649 creditor reference (SCOR) or without a structured reference (NON). A creditor reference can also support reconciliation; a normal IBAN does not inherently require manual matching.
A normal Swiss IBAN has an IID outside the QR-IID range of 30000–31999.
Reference Compatibility
- QR-IBAN: Requires a 27-digit QR reference, QRR.
- Normal CH/LI IBAN: Uses a creditor reference, SCOR, or no structured reference, NON.
Acceptance check: A QR reference with a normal IBAN is not a permitted combination. The approved contract must specify how the actual service reports that error.
Swiss QR Payment Sections and International Invoices
Swiss QR payment sections use CH or LI account details and CHF or EUR. This does not restrict invoicing to customers in those countries. Other currencies or non-QR-eligible account details need an appropriate alternative payment block on the invoice.
The QR-bill replaced the old payment slips on 1 October 2022; it is not mandatory for every invoice document. Keep address data structured and check the applicable SIX guidelines and transition guidance. A service cannot turn incorrect input into legally correct invoices in every case.
Next Step
Request the supported contract and approved test access through hello@magicheidi.ch. Clarify access, privacy and billing first. Then write a language-specific client and validate it with reproducible tests.