Let your Swiss customers pay WHMCS invoices with the Swiss QR-bill: scan, confirm, done.

Swiss QR Invoice adds the Swiss QR-bill (QR-Rechnung / QR-facture / QR-fattura) as a payment method in WHMCS. Every unpaid invoice gets:

• the Swiss QR Code;
• the payment part with receipt;
• the payee details, the invoice balance and a payment message with the invoice number.

Your customers scan the code with their banking app, or copy the details into e-banking. You receive a normal bank transfer, with no card fees and no payment provider in between.

Why use it?

The QR-bill is the standard payment slip in Switzerland and Liechtenstein: it has replaced the old red and orange payment slips (BV/ESR). Many Swiss businesses and private customers prefer paying invoices this way.

WHMCS has no built-in support for it. Swiss QR Invoice adds it as a regular payment gateway:

• you set everything up from Setup → Payment Gateways;
• the QR code is generated on your own server;
• no external service or API key is needed.

Key features

• All three QR-bill types, selectable in the gateway settings:

  • NON – IBAN without reference (payment message only); replaces the red payment slip.
  • SCOR – IBAN with ISO 11649 creditor reference (RF…) for automatic reconciliation, also for payments from abroad.
  • QRR – QR-IBAN with 27-digit QR reference; replaces the orange payment slip (ESR).

• Configurable reference. The reference is built from the invoice number or the invoice ID, with an optional prefix, for example the customer ID required by your bank. Check digits are calculated automatically.

• Payment message with the invoice number. For example "JetHosting 2026-0142". The prefix can be changed, and the message appears in every bill type.

• Online invoice. The client area invoice shows the QR code and the payment details (IBAN, payee, reference, message), each with a Copy button. You can place this block at the bottom of the invoice or in the payment section. The browser Print button prints the QR code at its real size (46 × 46 mm).

• PDF invoice with payment part. The full payment part with receipt (210 × 105 mm) goes on the invoice PDF:

  • at the bottom of the last page if there is room, otherwise on an extra page;
  • with the "Separate before paying in" line, the Swiss cross in the QR code, and the fonts, font sizes and corner marks required by the SIX style guide.

  It is also attached to the invoice emails.

• Payer details. The customer's name and address are filled in from the client profile, with street and house number split automatically for structured addresses. You can switch this off to leave a blank field with corner marks instead.

• Four languages. The payment part labels and client-area texts are available in Italian, German, French and English, chosen automatically from the client's language or set to a fixed language.

• Built-in configuration check. The gateway settings page shows:

  • the installed version;
  • the active bill type and the account in use;
  • a sample reference;
  • in red, anything that is missing or inconsistent (for example QRR without a QR-IBAN, or a QR-IBAN entered in the IBAN field).

• Standards-based. It follows the Swiss Implementation Guidelines QR-bill v2.3 (data version 0200, structured addresses) and the SIX style guide for the layout.

• No external dependencies. The QR code encoder and the payment part layout are part of the module. Nothing is sent to third parties to create the QR code.

• Apps & Integrations. The module ships with WHMCS metadata and a logo, so it appears under Apps & Integrations → Payments.

Integration with WHMCS

• It is a standard third-party payment gateway module (modules/gateways/swissqrinvoice.php). Settings are stored and encrypted by WHMCS like any other gateway.
• The online invoice uses the gateway's standard payment output. It works with Twenty-One and themes based on it, with no change to viewinvoice.tpl. With other themes the QR code stays in the payment section.
• For the PDF, you add a short, documented snippet at the end of invoicepdf.tpl, preferably in a child theme. Without it, the PDF invoice stays unchanged.
• A hook file in includes/hooks/ keeps the gateway out of checkout and the payment method menus while the license is not valid.

Licensing

A Swiss QR Invoice license from JetHosting.ch is required.

• Setup: enter the license key in the gateway settings. A status box shows whether the license is active, when it is due, and whether an update is available.
• Checks: the license is checked at most every few days. If the license server is unreachable, there is a grace period.
• When the license is not valid:
  • the gateway is hidden from checkout, from the invoice payment method menu and from the default payment method choice;
  • invoices already assigned to it show "temporarily unavailable";
  • the PDF is created without the payment part.
• Diagnostics: an admin-only page explains any license error in detail.

Requirements

• WHMCS 8.x or 9.x
• PHP 7.4 – 8.3 with OpenSSL (cURL recommended)
• IonCube Loader 14
• A Swiss or Liechtenstein bank account (IBAN, and a QR-IBAN for the QRR type)
• Invoices in CHF or EUR
• Outbound HTTPS from your WHMCS server to the license server

Installation

1. Upload the modules and includes folders to your WHMCS root folder.
2. Activate Swiss QR Invoice under Apps & Integrations or Setup → Payment Gateways.
3. Enter your IBAN or QR-IBAN, the payee name and address, the bill type and your license key.
4. Optional (recommended): add the snippet from the included guide to invoicepdf.tpl, so the payment part is printed on the PDF invoices.

FAQ

Are payments recorded in WHMCS automatically? No. The QR-bill is a bank transfer, so WHMCS gets no automatic confirmation. Record the payment when it reaches your account, manually or with a bank statement import. The payment message and, with SCOR/QRR, the reference make it easy to match the payment to the invoice.

Which bill type should I choose?

• NON is the simplest: it only needs your IBAN.
• SCOR adds a reference that your bank reports back, useful for automatic reconciliation.
• QRR is the successor of the orange ESR payment slip and needs a QR-IBAN from your bank.

You can switch at any time from the gateway settings.

Do I need to change my theme? No, not for the online invoice with Twenty-One or a theme based on it. For the PDF, add one short snippet to invoicepdf.tpl; the included guide shows exactly where.

Can customers outside Switzerland pay? Yes. Anyone with a bank account can pay by transfer using the IBAN and the payment message. The scan function, however, is typical of Swiss and Liechtenstein banking apps. The payee account itself must be Swiss or from Liechtenstein.

What about invoices in other currencies? The QR-bill standard only allows CHF and EUR. For invoices in other currencies the gateway shows a notice instead of the QR code.

Does the printed payment part meet the SIX requirements? The layout follows the SIX style guide, with sizes, fonts and positions as specified. Before using it in production, check a sample PDF with your bank or with the official SIX QR-bill validator. When printing, always use 100 % scale, not "fit to page".

Is any data sent to third parties? No data is sent to create the QR code. The only external connection is the license check with the JetHosting.ch license server. It sends the license key, domain, installation folder and module version, never invoice or customer data.

How do I uninstall it? Deactivate the gateway in WHMCS, delete modules/gateways/swissqrinvoice.php, the modules/gateways/swissqrinvoice/ folder and includes/hooks/swissqrinvoice.php, and remove the snippet from invoicepdf.tpl if you added it.

Italiano

Swiss QR Invoice

I clienti svizzeri pagano le fatture WHMCS con la QR-fattura: scansione, conferma, fatto.

Swiss QR Invoice aggiunge a WHMCS la QR-fattura svizzera (QR-Rechnung / QR-facture / QR-bill) come metodo di pagamento. Ogni fattura non pagata riceve:

• il codice QR svizzero;
• la sezione pagamento con ricevuta;
• i dati del beneficiario, il saldo della fattura e una causale con il numero di fattura.

Il cliente scansiona il codice con l'app della sua banca, oppure copia i dati nell'e-banking. Voi ricevete un normale bonifico, senza commissioni sulle carte e senza intermediari.

Perché usarlo?

La QR-fattura è la polizza di versamento standard in Svizzera e nel Liechtenstein: ha sostituito i vecchi bollettini rossi e arancioni (BV/PVR). Molte aziende e privati svizzeri preferiscono pagare le fatture così.

WHMCS non la supporta in modo nativo. Swiss QR Invoice la aggiunge come un normale gateway di pagamento:

• si configura tutto da Configurazione → Gateway di pagamento;
• il codice QR viene generato sul vostro server;
• non servono servizi esterni né chiavi API.

Caratteristiche principali

• Tutti e tre i tipi di QR-fattura, selezionabili nelle impostazioni del gateway:

  • NON – IBAN senza riferimento (solo causale); sostituisce il bollettino rosso.
  • SCOR – IBAN con riferimento creditore ISO 11649 (RF…) per la riconciliazione automatica, anche per pagamenti dall'estero.
  • QRR – QR-IBAN con riferimento QR di 27 cifre; sostituisce la polizza arancione (PVR).

• Riferimento configurabile. Il riferimento è generato dal numero fattura o dall'ID fattura, con un prefisso facoltativo, ad esempio l'ID cliente richiesto dalla banca. Le cifre di controllo sono calcolate automaticamente.

• Causale con il numero di fattura. Ad esempio "JetHosting 2026-0142". Il prefisso è modificabile e la causale compare in tutti i tipi.

• Fattura online. Nell'area clienti la fattura mostra il codice QR e i dati di pagamento (IBAN, beneficiario, riferimento, causale), ciascuno con il pulsante Copia. Il blocco può stare in fondo alla fattura o nella sezione di pagamento. Il pulsante Stampa del browser stampa il QR a misura reale (46 × 46 mm).

• PDF della fattura con la polizza. La sezione pagamento completa con ricevuta (210 × 105 mm) va nel PDF della fattura:

  • in fondo all'ultima pagina se c'è spazio, altrimenti su una pagina aggiuntiva;
  • con la dicitura "Da staccare prima del versamento", la croce svizzera nel QR, e i font, le dimensioni dei caratteri e gli angoli richiesti dallo Style Guide SIX.

  Arriva quindi anche con le email delle fatture.

• Dati del pagatore. Nome e indirizzo del cliente vengono presi dal profilo, con via e numero civico separati automaticamente per gli indirizzi strutturati. Disattivando l'opzione resta un campo vuoto con gli angoli.

• Quattro lingue. Le diciture della polizza e i testi dell'area clienti sono in italiano, tedesco, francese e inglese, scelti automaticamente in base alla lingua del cliente o impostati su una lingua fissa.

• Controllo della configurazione integrato. La pagina del gateway mostra:

  • la versione installata;
  • il tipo attivo e il conto usato;
  • un esempio di riferimento;
  • in rosso, cosa manca o non è coerente (ad esempio QRR senza QR-IBAN, o un QR-IBAN inserito nel campo IBAN).

• Conforme agli standard. Segue le Swiss Implementation Guidelines QR-bill v2.3 (versione dati 0200, indirizzi strutturati) e lo Style Guide SIX per l'impaginazione.

• Nessuna dipendenza esterna. Il generatore del codice QR e l'impaginazione della polizza fanno parte del modulo. Per creare il QR non viene inviato nulla a terzi.

• Apps & Integrations. Il modulo include i metadati WHMCS e un logo, quindi compare in Apps & Integrations → Payments.

Integrazione con WHMCS

• È un normale modulo gateway di pagamento di terze parti (modules/gateways/swissqrinvoice.php). Le impostazioni sono salvate e cifrate da WHMCS come per ogni altro gateway.
• La fattura online usa l'output di pagamento standard del gateway. Funziona con Twenty-One e i temi derivati senza modificare viewinvoice.tpl. Con altri temi il codice QR resta nella sezione di pagamento.
• Per il PDF si aggiunge alla fine di invoicepdf.tpl un breve snippet documentato, meglio in un tema figlio. Senza di esso il PDF della fattura resta invariato.
• Un file hook in includes/hooks/ toglie il gateway dal checkout e dai menu dei metodi di pagamento finché la licenza non è valida.

Licenza

Serve una licenza Swiss QR Invoice di JetHosting.ch.

• Attivazione: la chiave si inserisce nelle impostazioni del gateway. Un riquadro mostra se la licenza è attiva, la scadenza ed eventuali aggiornamenti disponibili.
• Verifiche: la licenza viene controllata al massimo ogni pochi giorni. Se il server licenze non risponde, c'è un periodo di tolleranza.
• Senza licenza valida:
  • il gateway sparisce dal checkout, dal menu del metodo di pagamento delle fatture e dalla scelta del metodo predefinito;
  • le fatture già assegnate mostrano "momentaneamente non disponibile";
  • il PDF viene generato senza polizza.
• Diagnosi: una pagina riservata agli amministratori spiega nel dettaglio ogni errore di licenza.

Requisiti

• WHMCS 8.x o 9.x
• PHP 7.4 – 8.3 con OpenSSL (cURL consigliato)
• IonCube Loader 14
• Un conto bancario svizzero o del Liechtenstein (IBAN, e QR-IBAN per il tipo QRR)
• Fatture in CHF o EUR
• Connessione HTTPS in uscita dal server WHMCS verso il server licenze

Installazione

1. Caricate le cartelle modules e includes nella cartella principale di WHMCS.
2. Attivate Swiss QR Invoice in Apps & Integrations o in Configurazione → Gateway di pagamento.
3. Inserite IBAN o QR-IBAN, nome e indirizzo del beneficiario, il tipo di QR-fattura e la chiave di licenza.
4. Facoltativo (consigliato): aggiungete a invoicepdf.tpl lo snippet della guida inclusa, per stampare la polizza nei PDF delle fatture.

Domande frequenti

I pagamenti vengono registrati automaticamente in WHMCS? No. La QR-fattura è un bonifico, quindi WHMCS non riceve una conferma automatica. Il pagamento va registrato quando arriva sul conto, a mano o con un import degli estratti bancari. La causale e, con SCOR/QRR, il riferimento rendono immediato collegare il pagamento alla fattura.

Quale tipo di QR-fattura scegliere?

• NON è il più semplice: basta l'IBAN.
• SCOR aggiunge un riferimento che la banca vi restituisce, utile per la riconciliazione automatica.
• QRR è il successore della polizza arancione (PVR) e richiede un QR-IBAN fornito dalla banca.

Potete cambiare tipo in qualsiasi momento dalle impostazioni del gateway.

Devo modificare il tema? No, per la fattura online con Twenty-One o un tema derivato. Per il PDF basta aggiungere un breve snippet a invoicepdf.tpl; la guida inclusa indica esattamente dove.

Possono pagare anche clienti fuori dalla Svizzera? Sì. Chiunque abbia un conto bancario può pagare con un bonifico usando IBAN e causale. La scansione del QR è però tipica delle app bancarie svizzere e del Liechtenstein. Il conto del beneficiario deve essere svizzero o del Liechtenstein.

E le fatture in altre valute? Lo standard QR-fattura ammette solo CHF ed EUR. Per le fatture in altre valute il gateway mostra un avviso al posto del codice QR.

La polizza stampata rispetta i requisiti SIX? L'impaginazione segue lo Style Guide SIX, con misure, font e posizioni come previsto. Prima dell'uso in produzione verificate un PDF di prova con la vostra banca o con il validatore ufficiale SIX. In stampa usate sempre la scala al 100 %, non "adatta alla pagina".

Vengono inviati dati a terzi? Per creare il QR non viene inviato nessun dato. L'unica connessione esterna è la verifica della licenza presso il server licenze di JetHosting.ch. Invia chiave di licenza, dominio, cartella di installazione e versione del modulo, mai dati di fatture o clienti.

Come si disinstalla? Disattivate il gateway in WHMCS, eliminate modules/gateways/swissqrinvoice.php, la cartella modules/gateways/swissqrinvoice/ e includes/hooks/swissqrinvoice.php, e togliete lo snippet da invoicepdf.tpl se l'avevate aggiunto.