action.skip

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_en_sample
Swiss QR-bill example, produced with JustOn

Info

The support for Swiss QR code invoices is available as of JustOn 2.64.

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.

Note

The Swiss QR code implementation differs from the general SEPA credit transfer QR code approach.

Be aware of the following specifics:

  • JustOn supports regular IBANs and, therefore, the Creditor Reference according to the ISO 11649 standard only. JustOn creates the ISO 11649 reference based on the invoice number.
  • For the payment reference, JustOn uses the invoice number (Invoice.Name) to create the ISO 11649 reference. 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 does currently not support QR-IBAN and QR-IID.

  • 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:

Object Required Field
Business Entity IBAN
Company
Street
Postal Code
City
Country Code
Invoice Account Name
Billing Street
Billing Postal Code
Billing City
Billing Country Code

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.

Info

JustOn recommends to enable the Template Layout v2 when working with templates that base on Liquid files. For details, see Enabling Template Layout v2.

  1. Create a new template, clone an existing template, or open an existing template.
  2. In the Layout & Design section, double-click 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, double-click 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, double-click 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.

Note

Do not change the CSS or HTML sections for the payment slip. Otherwise, your invoice template may no longer comply with the standard.

Related information:

Working With Templates