Setting Up Swiss QR Code Invoices

Swiss invoices usually include a payment slip. Starting mid-2020, Switzerland has introduced the QR-bill, successively replacing the traditional payment slips. The QR-bill includes a QR code that holds the payment-relevant information. All market participants must technically be able to issue and process QR-bills.

With this respect, JustOn supports generating invoices that include the Swiss QR code.

Swiss QR-bill example, produced with JustOn

Implementation Details

The implementation in JustOn Billing & Invoice Management adheres to the Swiss Implementation Guidelines QR-bill, version 2.1, and validates against the QR-bill validator.

Be aware of the following specifics:

• JustOn supports both

  • Regular IBANs and, therefore, the Creditor Reference according to the ISO 11649 standard (SCOR)

    JustOn creates the ISO 11649 reference (also referred to as structured remittance information) based on the invoice number.

  • QR-IBAN with a QR reference (QRR)

    If set up accordingly, JustOn generates a 27-digit QRR reference and embeds it in the Swiss QR code instead of the IBAN/SCOR combination. For details, see Using QR-IBAN.

• For the payment reference, JustOn uses the invoice number (Invoice.Name) to create the ISO 11649 reference when the Add QR Code field on the related template is set to Swiss QR Code (see Configuring QR Code Template). The reference is written to the Invoice field Payment Reference on invoice finalization, overwriting any existing value. The payment reference is part of the data to be encoded in the QR code.

  If the invoice number contains more than 21 characters, JustOn Billing & Invoice Management uses a hash algorithm to convert the number, creating a suitable, unique payment reference.

• JustOn requires the complete address information for both the business entity and the invoice recipient (billing address). Blank fields for sender or recipient produce errors.

• JustOn does currently not support the QR-bill fields Billing information and Alternative procedures.

For the QR code invoice to work, JustOn requires the following data specified on the business entity and the invoice:

Once set up accordingly, JustOn prints the QR-code payment slip on a new page at the end of the invoice PDF.

Configuring QR Code Template

The PDF generation for QR code invoices relies on the JustOn PDF service, which requires a Liquid template.

1. Create a new template, clone an existing template, or open an existing template.
2. In the Layout & Design section, click next to the PDF Renderer field and specify the value v2.

3. Attach the required Liquid template files.

   In the Notes & Attachments area, click to open the action menu, select Upload Files, then proceed as prompted.

   You can use the following Liquid templates as a starting point:

   Swiss QR Code Invoice Template (English)
   Swiss QR Code Invoice Template (German)

   This operation requires the custom Type field (ONB2__Type__c) to be available on the page layout of the Content Version object. For details about adding fields to page layouts, see Modifying Page Layouts or Search Layouts.

   Make sure to set the Type of the uploaded files to Liquid Template. The picklist value Liquid Template may not be available in your org. In this case, add it to the value picklist for the Type field of the Content Version object. For details, see Modifying Picklist Values.

4. In the Add QR Code field, select Swiss QR Code.

   This operation requires the custom Add QR Code field (ONB2__AddQRCode__c) to be available on the page layout of the Template object. For details about adding fields to page layouts, see Modifying Page Layouts or Search Layouts.

5. In the Layout & Design section, click next to the PDF Options field and specify options for the PDF output as required.

   The field value is in JSON notation and sets optional properties for the decimal, currency and percent Liquid filters.

   Property	Description
   locale	Sets the language code.
   currencyDisplay	Defines the currency display format. Possible values include symbol, code, name.
   useDigitGrouping	Toggles the digit group separator. Possible values include true or false.
   minimumFractionDigits	Sets the minimum number (Integer) of decimal places.
   maximumFractionDigits	Sets the maximum number (Integer) of decimal places.

   JustOn recommends to set at least the locale property. It defaults to en-EN if not set.

6. Optionally, define a page header and footer.

   In the Header & Footer section, click next to the Page Header or Footer field and specify the information as required.

   Page header, footer and page counters must be addressed using specific CSS classes. You may use the following code as a starting point for your customization:

   • Page header

     <div class="page-header" style="width:90%; text-align:center; font-size:10pt;"></div>
     

   • Footer

     <div class="page-footer" style="width:90%; text-align:center; font-size:10pt;">
         Page <span class="pageNumber"></span> of <span class="totalPages"></span>
     </div>
     

7. Click Save to apply your template customization.

   You can now apply this template to invoices with recipients in Switzerland. When generating the PDF file, the QR-code payment slip will be printed accordingly.

Using QR-IBAN

As an alternative to regular IBANs with an ISO 11649 reference (SCOR), JustOn Billing & Invoice Management supports Swiss QR-IBANs with a QR reference (QRR). A QR-IBAN uses a dedicated bank identification (IID) in the range 30000–31999. Unlike a regular IBAN, it makes the payment reference a mandatory field in the payer's e-banking, which enables fully automatic payment matching. For details, see Swiss QR-bill.

To use a QR-IBAN, you specify it in the QR-IBAN field on the business entity.

Be aware of the following specifics:

• If the QR-IBAN field is set, JustOn Billing & Invoice Management generates a QRR reference – a 27-digit numeric reference including a check digit – based on the invoice number on invoice finalization, instead of the ISO 11649 reference. As with the ISO 11649 reference, JustOn writes the value to the Invoice field Payment Reference, and encodes it in the QR code. The QR code then uses the QR-IBAN and the reference type QRR.
• If the QR-IBAN field is empty, the software uses the regular IBAN and the ISO 11649 reference as before.

• The regular IBAN field remains required and is used to specify the bank account number. The QR-IBAN is an additional, optional field.

  The QR-IBAN must be a valid Swiss QR-IBAN (IID range 30000–31999). An invalid value produces an error when the invoice PDF is rendered.

A QRR reference is grouped differently than an ISO 11649 reference, and JustOn provides a dedicated template field for each. This is why invoice templates that include the Swiss QR payment slip must be updated to display the correct reference for each type:

1. Navigate to the relevant template record.

2. In the attached Liquid template file for invoices (most likely, Invoice template.liquid), replace the reference output wherever the payment reference is displayed.

   Use the following code:

   {% if QrCode.structuredData.reference.type == 'QRR' %}
       {{ QrCode.structuredData.reference.printQrr }}
   {% else %}
       {{ QrCode.structuredData.reference.printIso11649 }}
   {% endif %}
   

Related information:

Working With Templates