SwissQrBill (swiss_qr_bill v0.1.2)

Copy Markdown View Source

Swiss QR-bill generation library per SIX IG QR-bill v2.3.

Generates the complete payment part (Zahlteil) with receipt in three output formats: PDF, SVG (text as paths), and PNG (rasterized at configurable DPI).

Output formats

  • to_pdf/2 — native PDF (no system dependencies)
  • to_svg/2 — SVG with text converted to paths (requires pdftocairo)
  • to_png/2 — rasterized PNG at configurable DPI (requires pdftocairo)

Output sizes

  • :payment_slip — 210 x 105 mm (default)
  • :a4 — 210 x 297 mm (payment slip at bottom)
  • :qr_code — 56 x 56 mm (QR code only)

Languages

:de, :fr, :it, :en, :rm (Romansh)

Usage

creditor = SwissQrBill.Address.new("Muster AG", "Bahnhofstrasse", "1", "8001", "Zürich", "CH")
debtor = SwissQrBill.Address.new("Max Muster", "Hauptstrasse", "42", "3000", "Bern", "CH")
{:ok, ref} = SwissQrBill.Reference.QrReferenceGenerator.generate("210000", "313947143000901")

bill =
  SwissQrBill.new()
  |> SwissQrBill.set_creditor(creditor)
  |> SwissQrBill.set_creditor_information("CH44 3199 9123 0008 8901 2")
  |> SwissQrBill.set_payment_amount("CHF", 2500.25)
  |> SwissQrBill.set_debtor(debtor)
  |> SwissQrBill.set_payment_reference(:qrr, ref)
  |> SwissQrBill.set_additional_information("Invoice 2024-001")

{:ok, pdf} = SwissQrBill.to_pdf(bill, language: :de)
{:ok, svg} = SwissQrBill.to_svg(bill, language: :de)
{:ok, png} = SwissQrBill.to_png(bill, language: :de, dpi: 300)

Summary

Types

t()

Functions

add_alternative_scheme(bill, parameter)

Adds an alternative scheme. Maximum 2 allowed.

new()

Creates a new empty QR bill.

set_additional_information(bill, message, bill_information \\ nil)

Sets additional information (unstructured message and/or bill information).

set_creditor(bill, address)

Sets the creditor address.

set_creditor_information(bill, iban)

Sets the creditor IBAN. Accepts an IBAN string or a CreditorInformation struct.

set_debtor(bill, address)

Sets the debtor address. Optional.

set_payment_amount(bill, currency, amount \\ nil)

Sets the payment amount. Amount can be nil for bills without a fixed amount.

set_payment_reference(bill, type, reference \\ nil)

Sets the payment reference.

to_pdf(bill, opts \\ [])

Generates the complete payment part as PDF binary. Validates the bill first.

to_png(bill, opts \\ [])

Generates the complete payment part as PNG. Rasterized from the PDF at the specified DPI for print-quality output. Requires pdftocairo (poppler-utils) to be installed.

to_svg(bill, opts \\ [])

Generates the complete payment part as SVG. Text is converted to glyph outlines (paths) for guaranteed rendering on all devices. Requires pdftocairo (poppler-utils) to be installed.

validate(bill)

Validates the QR bill data. Returns {:ok, bill} or {:error, errors}.

Types

t()

@type t() :: %SwissQrBill{
  additional_information: SwissQrBill.AdditionalInformation.t() | nil,
  alternative_schemes: [SwissQrBill.AlternativeScheme.t()],
  creditor: SwissQrBill.Address.t() | nil,
  creditor_information: SwissQrBill.CreditorInformation.t() | nil,
  debtor: SwissQrBill.Address.t() | nil,
  payment_amount: SwissQrBill.PaymentAmount.t() | nil,
  payment_reference: SwissQrBill.PaymentReference.t() | nil
}

Functions

add_alternative_scheme(bill, parameter)

@spec add_alternative_scheme(t(), String.t()) :: t()

Adds an alternative scheme. Maximum 2 allowed.

new()

@spec new() :: t()

Creates a new empty QR bill.

set_additional_information(bill, message, bill_information \\ nil)

@spec set_additional_information(t(), String.t() | nil, String.t() | nil) :: t()

Sets additional information (unstructured message and/or bill information).

set_creditor(bill, address)

@spec set_creditor(t(), SwissQrBill.Address.t()) :: t()

Sets the creditor address.

set_creditor_information(bill, iban)

@spec set_creditor_information(t(), String.t() | SwissQrBill.CreditorInformation.t()) ::
  t()

Sets the creditor IBAN. Accepts an IBAN string or a CreditorInformation struct.

set_debtor(bill, address)

@spec set_debtor(t(), SwissQrBill.Address.t()) :: t()

Sets the debtor address. Optional.

set_payment_amount(bill, currency, amount \\ nil)

@spec set_payment_amount(t(), String.t(), float() | nil) :: t()

Sets the payment amount. Amount can be nil for bills without a fixed amount.

set_payment_reference(bill, type, reference \\ nil)

@spec set_payment_reference(
  t(),
  SwissQrBill.PaymentReference.reference_type(),
  String.t() | nil
) :: t()

Sets the payment reference.

to_pdf(bill, opts \\ [])

@spec to_pdf(
  t(),
  keyword()
) :: {:ok, binary()} | {:error, any()}

Generates the complete payment part as PDF binary. Validates the bill first.

Options

  • :language — :de, :fr, :it, :en, or :rm (default: :de)
  • :output_size — :payment_slip (210x105mm), :a4 (210x297mm), or :qr_code (56x56mm). Default: :payment_slip
  • :branding — when true, adds a small localized "Created by qrbill.dev" line (default: false). With :qr_code the canvas grows by 4mm to fit the line below the code.

to_png(bill, opts \\ [])

@spec to_png(
  t(),
  keyword()
) :: {:ok, binary()} | {:error, any()}

Generates the complete payment part as PNG. Rasterized from the PDF at the specified DPI for print-quality output. Requires pdftocairo (poppler-utils) to be installed.

Options

  • :language — :de, :fr, :it, :en, or :rm (default: :de)
  • :output_size — :payment_slip (210x105mm), :a4 (210x297mm), or :qr_code (56x56mm). Default: :payment_slip
  • :dpi — resolution (default: 300)
  • :branding — when true, adds a small localized "Created by qrbill.dev" line (default: false)

to_svg(bill, opts \\ [])

@spec to_svg(
  t(),
  keyword()
) :: {:ok, binary()} | {:error, any()}

Generates the complete payment part as SVG. Text is converted to glyph outlines (paths) for guaranteed rendering on all devices. Requires pdftocairo (poppler-utils) to be installed.

Options

  • :language — :de, :fr, :it, :en, or :rm (default: :de)
  • :output_size — :payment_slip (210x105mm), :a4 (210x297mm), or :qr_code (56x56mm). Default: :payment_slip
  • :branding — when true, adds a small localized "Created by qrbill.dev" line (default: false)

validate(bill)

@spec validate(t()) :: {:ok, t()} | {:error, [String.t()]}

Validates the QR bill data. Returns {:ok, bill} or {:error, errors}.