Displays a Swiss QR-bill.

This class implements version 2.2 of the Swiss QR-bill specification but takes into account version 2.3 where appropriate.

Requirements¶ ↑

• Liberation Sans TrueType font installed in standard Linux path (or changed via the configuration option, see next section)

• Rubygem rqrcode_core for generating the QR code

Configuration option ‘layout.swiss_qr_bill’¶ ↑

The configuration option ‘layout.swiss_qr_bill’ is a hash containing styling information for the various text parts: section heading, payment heading/value, receipt heading/value and the alternative procedures. The default values are taking from the QR-bill style guide.

The keys of this hash are strings of the form ‘part.subpart.property’ where

• ‘part’ can be ‘section’, ‘payment’, ‘receipt’, or ‘alternative_procedures’,

• ‘subpart’ can be ‘heading’ or ‘value’ (the latter not for ‘section’),

• ‘property’ can be ‘font’, ‘font_size’ or ‘line_height’ (the latter not for ‘section’).

The default font is Liberation Sans which is one of the four allowed fonts (the others being Arial, Frutiger, and Helvetica). The font files themselves are not included and the ‘font’ property, by default, references the standard Linux path where the fonts would be found. Note that all ‘*.heading.font’ values should reference the bold version of the font whereas the ‘*.value.font’ values should reference the regular version.

Data Structure¶ ↑

All the necessary information for generating the Swiss QR-bill is provided on initialization. The following keys can be used:

:lang

The language to use for the literal text strings appearing in the QR-bill. One of :en, :de, :fr or :it.

Defaults to :en if not specified.

:creditor

(required) The creditor of the transaction. This is a hash that can contain the following elements:

:iban

(required) The IBAN of the creditor (21 characters, only IBANs for CH or LI). The IBAN is only validated with respect to its check digits.

:name

(required) The name of the creditor (maximum 70 characters).

:address_type

(required) The type of address, either :structured or :combined. Defaults to :structured which is the only choice in version 2.3 of the specification.

:address_line1

The first line of the creditor’s address (maximum 70 characters). In case of a structured address, this is the street. Otherwise this has to be the street and building number together.

:address_line2

The second line of the creditor’s address. In case of a structured address, this has to be the building number (maximum 16 characters). Otherwise it has to be the postal code and town (maximum 70 characters).

:postal_code

The postal code of the creditor’s address (maximum 16 characters, only for structured addresses).

:town

The town from the creditor’s address (maximum 35 characters, only for structured addresses).

:country

(required) The country from the creditor’s address (ISO 3166-1 two-letter country code).

:debtor

The debtor information for the transaction. This information is optional but if used some elements are required. The value is a hash that can contain the same elements as the :creditor key with the exception of the :iban.

:amount

The payment amount (between 0.01 and 999,999,999.99). If not filled in, a blank field is shown for adding the amount by hand later. If the amount is set to zero, it means that the QR-bill should be used as notification and the :message is set according to the specification.

:currency

(required) The payment currency (either CHF or EUR).

:reference_type

The payment reference type (either QRR, SCOR or NON). Defaults to NON.

:reference

The structured reference data. All whitespace is removed before processing.

In case of a QRR reference, the value has to be a 26 digit reference without check digit or a 27 digit reference with check digit. The check digit is validated.

In case of a SCOR reference, the value has to contain between 5 and 25 alpha-numeric characters. The check digits are validated.

:message

Additional, unstructured information (maximum 140 characters).

:billing_information

Billing information for automated booking of the payment (maximum 140 characters).

:alternative_schemes

Alternative schemes parameters. Either a single string with a maximum of 100 characters or an array of two such strings.

Example¶ ↑

HexaPDF::Composer.create("sample-qr-bill.pdf", margin: 0) do |composer|
  data = {
   lang: :de,
   creditor: {
     iban: "CH44 3199 9123 0008 8901 2",
     name: "Max Muster & Söhne",
     address_line1: "Musterstrasse",
     address_line2: "123",
     postal_code: "8000",
     town: "Seldwyla",
     country: "CH",
   },
   debtor: {
     address_type: :combined,
     name: "Simon Muster",
     address_line1: "Musterstrasse 1",
     address_line2: "8000 Seldwyla",
     country: "CH"
   },
   amount: 2500.25,
   currency: 'CHF',
  }
  composer.swiss_qr_bill(data: data, style: {valign: :bottom})
end

References¶ ↑

• Website www.six-group.com/en/products-services/banking-services/billing-and-payments/qr-bill.html

• 2.2 Specification www.six-group.com/dam/download/banking-services/standardization/qr-bill/ig-qr-bill-v2.2-en.pdf

• 2.3 Specification www.six-group.com/dam/download/banking-services/standardization/qr-bill/ig-qr-bill-v2.3-en.pdf

• Style guide www.six-group.com/dam/download/banking-services/standardization/qr-bill/style-guide-qr-bill-en.pdf