qrbill

README

qrbill Go package

The qrbill package implements generating QR-bill QR codes, which is a Swiss 🇨🇭 payment standard:

• launch announcement

• Specification: Swiss Implementation Guidelines QR-bill
  (version 2.1 from 30 September 2019 at the time of writing)

These QR codes fill in details of a bank wire transfer, either all fields or just some of them.

Recipients can scan the QR code with their mobile banking app, or with their online banking web site’s mobile scan functionality, making it much easier to send a wire transfer.

An example use case is for an association or club: you can send out payment instructions to your members to collect membership fees (“Einzahlungsschein”).

Validity

The SIX QR-bill validation portal successfully confirms that e.g. the code at the top right is valid.

qrbill API (Example program)

To install the program:

go install github.com/stapelberg/qrbill/cmd/...

To run the program, run qrbill-api in the terminal. You will see an output like this:

% qrbill-api
2020/06/25 23:32:52 QR Bill generation URL: http://localhost:9933/qr?format=html

You can append the URL parameters on the left to customize the code. E.g.:

http://localhost:9933/qr?format=html&udname=Mary+Jane&udaddr1=Artikel+19b

When you open the URL in your web browser, you should see the following debug output:

When you scan the resulting QR code with your eBanking app, you should see a form like this:

Once you are happy with the code parameters, change the format parameter from html to png, e.g.:

http://localhost:9933/qr?format=png&udname=Mary+Jane&udaddr1=Artikel+19b

Auto-starting qrbill on macOS

See also Script management with launchd in Terminal on Mac for more details from Apple.

1. Copy qrbill-api to /Applications
2. Copy launchd/net.zekjur.qrbill.plist to –/Library/LaunchAgents
3. Restart your computer, or run launchctl load –/Library/LaunchAgents/net.zekjur.qrbill.plist

Crowd-sourced compatibility testing

To build confidence in our implementation, please help us verify that the codes scan as expected!

qrbill v0.1.5 (2020-Nov-07)

Scan each of the following 3 QR codes in your eBanking app, program or web interface, then file an issue (or send a pull request) with your test results! Thank you very much.

donation	invoice	invoice without amount
expected message: Spende 420	expected sender address Mary Jane, expected amount 23.42 CHF	(without amount)
donation parameters	invoice parameters	invoice without amount parameters

QR code	scanned with	paid via	Notes
donation	SIX QR-bill validation
invoice	SIX QR-bill validation
invoice without amount	SIX QR-bill validation
donation	ZKB eBanking (iOS)	ZKB
invoice	ZKB eBanking (iOS)
invoice without amount	ZKB eBanking (iOS)
donation	Revolut (iOS)
invoice	Revolut (iOS)		message replaced with revolut text!
invoice without amount	Revolut (iOS)		message replaced with revolut text!

qrbill v0.1.4 (2020-Sep-21)

Scan each of the following 3 QR codes in your eBanking app, program or web interface, then file an issue (or send a pull request) with your test results! Thank you very much.

donation	invoice	invoice without amount
expected message: Spende 420	expected sender address Mary Jane, expected amount 23.42 CHF	(without amount)
donation parameters	invoice parameters	invoice without amount parameters

QR code	scanned with	paid via	Notes
donation	SIX QR-bill validation
invoice	SIX QR-bill validation
invoice without amount	SIX QR-bill validation
donation	ZKB eBanking (iOS)	ZKB
invoice	ZKB eBanking (iOS)
invoice without amount	ZKB eBanking (iOS)
donation	Revolut (iOS)
invoice	Revolut (iOS)		message replaced with revolut text!
invoice without amount	Revolut (iOS)		message replaced with revolut text!
donation	UBS (iOS)
invoice	UBS (iOS)
invoice without amount	UBS (iOS)
donation	Postfinance (Android)
invoice	Postfinance (Android)
invoice without amount	Postfinance (Android)
donation	Raiffeisen (Android)
invoice	Raiffeisen (Android)
invoice without amount	Raiffeisen (Android)
donation	UBS (Android)
invoice	UBS (Android)
invoice without amount	UBS (Android)
donation	Credit Suisse (iOS)
invoice	Credit Suisse (iOS)
invoice without amount	Credit Suisse (iOS)
donation	ZKB eBanking (Android)
invoice	ZKB eBanking (Android)
invoice without amount	ZKB eBanking (Android)
donation	Zak - Bank Cler (Android)
invoice	Zak - Bank Cler (Android)		no mention of "Mary Jane" or "Artikel 19b"
invoice without amount	Zak - Bank Cler (Android)		no mention of "Mary Jane" or "Artikel 19b"

qrbill v0.1.3 (2020-Sep-10)

donation	invoice	invoice without amount
donation parameters	invoice parameters	invoice without amount parameters

QR code	scanned with	paid via	Notes
donation	SIX QR-bill validation
invoice	SIX QR-bill validation
invoice without amount	SIX QR-bill validation
donation	ZKB eBanking (iOS)	ZKB
invoice	ZKB eBanking (iOS)
invoice without amount	ZKB eBanking (iOS)
donation	Revolut (iOS)
invoice	Revolut (iOS)		message replaced with revolut text!
invoice without amount	Revolut (iOS)		message replaced with revolut text!
donation	Zak - Bank Cler (Android)		no mention of "Mary Jane" or "Artikel 19"
invoice	Zak - Bank Cler (Android)		no mention of "Mary Jane" or "Artikel 19"
invoice without amount	Zak - Bank Cler (Android)		no mention of "Mary Jane" or "Artikel 19"
donation	Bank Linth (iOS)
invoice	Bank Linth (iOS)
invoice without amount	Bank Linth (iOS)

Documentation

Overview

Package qrbill implements the Swiss QR-bill standard.

More specifically, the most recent standard version at the time of writing was the Swiss Payment Standards 2019 Swiss Implementation Guidelines QR-bill Version 2.1, to be found at:

https://www.six-group.com/dam/download/banking-services/standardization/qr-bill/ig-qr-bill-v2.1-en.pdf (English) https://www.six-group.com/dam/download/banking-services/standardization/qr-bill/ig-qr-bill-v2.1-de.pdf (German)

Note

QRR and SCOR references are not yet implemented.

Index

• Constants
• type Address
  • func (a Address) Validate() Address
• type AddressType
• type Bill
  • func (b *Bill) EncodeToEPS() ([]byte, error)
  • func (b *Bill) EncodeToImage() (image.Image, error)
  • func (b *Bill) EncodeToPDF() ([]byte, error)
  • func (b *Bill) EncodeToSVG() ([]byte, error)
  • func (b *Bill) EncodeToString() string
• type Image
  • func (i *Image) Encode(w io.Writer, ids map[string]pdf.ObjectID) error
  • func (i *Image) Objects() []pdf.Object
• type QRCH
  • func (q *QRCH) Encode() (*Bill, error)
  • func (q *QRCH) Validate() *QRCH
• type QRCHCcyAmt
  • func (a QRCHCcyAmt) Validate() QRCHCcyAmt
• type QRCHCdtrInf
• type QRCHHeader
• type QRCHRmtInf
• type QRCHRmtInfAddInf

Constants

const (
	// QRType is an unambiguous indicator for the Swiss QR Code. Fixed value.
	QRType = "SPC" // Swiss Payments Code

	// Version contains the version of the specifications (Implementation
	// Guidelines) in use on the date on which the Swiss QR Code was
	// created. The first two positions indicate the main version, the following
	// two positions the sub-version. Fixed value.
	Version = "0200" // Version 2.0

	// CodingType is the character set code. Fixed value.
	CodingType = "1" // UTF-8 restricted to the Latin character set

	// Trailer is an unambiguous indicator for the end of payment data. Fixed
	// value.
	Trailer = "EPD" // End Payment Data
)

Types

type Address

type Address struct {
	AdrTp            AddressType
	Name             string // Name, max 70. chars, first name + last name, or company name
	StrtNmOrAdrLine1 string // Street or address line 1
	BldgNbOrAdrLine2 string // Building number or address line 2
	PstCd            string // Postal code, max 16 chars, must be provided without a country code prefix
	TwnNm            string // Town, max. 35 chars
	Ctry             string // Country, two-digit country code according to ISO 3166-1
}

func (Address) Validate

func (a Address) Validate() Address

type AddressType

type AddressType string

AddressType corresponds to AdrTp in ISO20022.

const (
	AddressTypeStructured AddressType = "S"
	AddressTypeCombined   AddressType = "K"
)

type Bill

type Bill struct {
	// contains filtered or unexported fields
}

func (*Bill) EncodeToEPS

func (b *Bill) EncodeToEPS() ([]byte, error)

func (*Bill) EncodeToImage

func (b *Bill) EncodeToImage() (image.Image, error)

func (*Bill) EncodeToPDF

func (b *Bill) EncodeToPDF() ([]byte, error)

func (*Bill) EncodeToSVG

func (b *Bill) EncodeToSVG() ([]byte, error)

func (*Bill) EncodeToString

func (b *Bill) EncodeToString() string

type Image

type Image struct {
	pdf.Common

	Bounds image.Rectangle
}

Image represents a PDF image object containing a DIN A4-sized page scanned with 600dpi (i.e. into 4960x7016 pixels).

func (*Image) Encode

func (i *Image) Encode(w io.Writer, ids map[string]pdf.ObjectID) error

Encode implements Object.

func (*Image) Objects

func (i *Image) Objects() []pdf.Object

Objects implements Object.

type QRCH

type QRCH struct {
	Header    QRCHHeader  // Header
	CdtrInf   QRCHCdtrInf // Creditor information (Account / Payable to)
	UltmtCdtr Address     // (must not be filled in, for Future Use)
	CcyAmt    QRCHCcyAmt  // Paymount amount information
	UltmtDbtr Address     // Ultimate Debtor
	RmtInf    QRCHRmtInf  // Payment reference
}

func (*QRCH) Encode

func (q *QRCH) Encode() (*Bill, error)

func (*QRCH) Validate

func (q *QRCH) Validate() *QRCH

type QRCHCcyAmt

type QRCHCcyAmt struct {
	Amt string // Amount
	Ccy string // Currency
}

func (QRCHCcyAmt) Validate

func (a QRCHCcyAmt) Validate() QRCHCcyAmt

type QRCHCdtrInf

type QRCHCdtrInf struct {
	IBAN string
	Cdtr Address // Creditor
}

type QRCHHeader

type QRCHHeader struct {
	QRType  string
	Version string
	Coding  string
}

type QRCHRmtInf

type QRCHRmtInf struct {
	Tp     string           // Reference type
	Ref    string           // Reference
	AddInf QRCHRmtInfAddInf // Additional information
}

type QRCHRmtInfAddInf

type QRCHRmtInfAddInf struct {
	Ustrd   string // Unstructured message
	Trailer string // Trailer
}