Advanced usage Payload generators

1. Introduction to the "Payload Generator"
2. Overview of the different payload types
3. Usage of the payload generators
   3.1 BezahlCode
   3.2 Bitcoin Payment Address
   3.3 Bookmark
   3.4 Calendar events (iCal/vEvent)
   3.5 ContactData (MeCard/vCard)
   3.6 Geolocation
   3.7 Girocode
   3.8 Mail
   3.9 MMS
   3.10 Monero address/payment
   3.11 One-Time-Password
   3.12 Phonenumber
   3.13 Shadowsocks configuration
   3.14 Skype call
   3.15 SMS
   3.16 SwissQrCode (ISO-20022)
   3.17 URL
   3.18 WhatsAppMessage
   3.19 WiFi
4. Development of own payload types

1. Introduction to the "Payload Generator"

The payload generator is on the things, which make the QRCoder unique. It's a class which helps to generate special payloads (the text encoded in QR codes) that will start different actions on the device which scans the QR code.

Indeed a QR code can only encode a string (of text), but if this string has a special format, most* QR code scanners will perform a predefined action.

To help you to create these special formatted payload strings, we implemented the payload generators. These are easy-to-use classes, which check your data for invalid inputs and automagically create the fitting payload strings for you.

Info: Keep in mind, that all payload types stand and fall with the commitment between QR encoders and QR scanner apps. Special payload types aren't defined in the QR code standard (ISO/IEC 18004). Most of the QR code scanner apps are able to interpret the payload types described on this page. But in a real world application you should test your QR codes against the scanners your users will use.

2. Overview of the different payload types

Right now there are 19 different payload generators. To get a quick overview, have a look at the following table.

(Class-)Name	What does it do, when scanned?	Specification
BezahlCode	Opens the banking app for bank transfers, debits and banker's order. It's common in German-speaking countries and competes with the more common GiroCode.	Bezahlcode specification
BitcoinAddress	Starts Bitcoin app for transfers.	BIP 0021
Bookmark	Saves a bookmark to the default webbrowser.	NTTdocomo MEBKM
CalendarEvent	Adds an event to the user's calendar. Supports iCal and vEvent format.	RFC 5545
ContactData	Adds a contact to the user's address book. Supports MeCard, vCard 2.1, vCard 3.0 and vCard 4.0 format.	NTTdocomo MeCard, RFC 2425 (vCard 2.1), RFC 2426 (vCard 3.0), RFC 6350 (vCard 4.0)
Geolocation	Opens the maps app and shows the given location or opens Google Maps in browser.	RFC 5870
Girocode	Opens the banking app for bank transfers. It's common in the European region and competes with the less common BezahlCode.	EPC069-12
Mail	Opens the default email app and composes a new message. Supports mailto:, MATMSG: and smtp: format.	RFCRFC 6068, NTTdocomo MATMSG, smtp URI scheme
MMS	Opens the standard messaging app and composes a new MMS. Either in mmsto: or in mms: format.	RFC draft (mmsto), Data Services: Whitepaper (mms)
MoneroTransaction	Opens the Monero wallet with transaction details.	Monero URI scheme
OneTimePassword	Encoded secret keys. May be used in combination with Google Authenticator for example.	Key URI Format
PhoneNumber	Opens the phone's dialer app with given number.	RFC 3966
ShadowSocksConfig	Opens ShadowSocks app with given configuration.	ShadowSocks URI scheme
SkypeCall	Opens Skype app and calls given contact.	Skype URI API reference
SMS	Open SMS app and composes new message. Supports sms:, sms: (for iOS) and SMSTO: format.	RFC 5724 (sms), sms URI for iOS, SMSTO (not common)
SwissQrCode	Opens a banking app for bank transfer or donations. Mostly common in Switzerland. Will be part of the new "QR-Rechnung" (former Einzahlungsschein).	ISO 20022
Url	Opens the given URL in default webbrowser.	RFC 3986
WhatsAppMessage	Open whatsapp, lets you choose a contact and composes a new message with given text.	WhatsApp URL Scheme
WiFi	When scanned, the scanning device can login to the given WiFi without typing the credentials.	Short description

3. Usage of the payload generators

3.1 BezahlCode

Classname/Classfile: BezahlCode / PayloadGenerator.cs

When to use?

Use it for banking (inlcuding bank transfers, debits, bank contacts and banker's order). It's used in German-speaking countries and competes with the more common GiroCode.

How to use it - simple way

The following code generates a payload for a simple SEPA payment to Wikimedia.

BezahlCode generator = new BezahlCode(BezahlCode.AuthorityType.singlepaymentsepa, "Wikimedia", iban: "DE33100205000001194700", bic: "BFSWDE33BER", amount: 25.00m);
string payload = generator.ToString();

QRCodeGenerator qrGenerator = new QRCodeGenerator();
QRCodeData qrCodeData = qrGenerator.CreateQrCode(payload, QRCodeGenerator.ECCLevel.Q);
QRCode qrCode = new QRCode(qrCodeData);
var qrCodeAsBitmap = qrCode.GetGraphic(20);

Parameter table

There are four overloads:

Overload 1
Description: Creates a payload for SEPA-based payments and transfers

Parameter name	Type	Default	Description
authority	AuthorityType		Type of the bank transfer
name	string		Name of the receiver (Empfänger)
iban	string		IBAN
bic	string		BIC
amount	decimal		Amount (Betrag)
periodicTimeunit	string	""	Unit of intervall for payment ('M' = monthly, 'W' = weekly)
periodicTimeunitRotation	int	0	Intervall for payment. This value is combined with 'periodicTimeunit'
periodicFirstExecutionDate	DateTime?	null	Date of first periodic execution
periodicLastExecutionDate	DateTime?	null	Date of last periodic execution
creditorId	string	""	Creditor id (Gläubiger ID)
mandateId	string	""	Manadate id (Mandatsreferenz)
dateOfSignature	DateTime?	null	Signature date (Erteilungsdatum des Mandats)
reason	string	""	Reason (Verwendungszweck)
sepaReference	string	""	SEPA reference (SEPA-Referenz)
currency	Currency	Currency.EUR	Currency (Währung)
executionDate	DateTime?	null	Execution date (Ausführungsdatum)

Overload 2
Description: Creates a payload for non SEPA-based payments and transfers

Parameter name	Type	Default	Description
authority	AuthorityType		Type of the bank transfer
name	string		Name of the receiver (Empfänger)
account	string		Bank account (Kontonummer)
bnc	string		Bank institute (Bankleitzahl)
amount	decimal		Amount (Betrag)
periodicTimeunit	string	""	Unit of intervall for payment ('M' = monthly, 'W' = weekly)
periodicTimeunitRotation	int	0	Intervall for payment. This value is combined with 'periodicTimeunit'
periodicFirstExecutionDate	DateTime?	null	Date of first periodic execution
periodicLastExecutionDate	DateTime?	null	Date of last periodic execution
reason	string	""	Reason (Verwendungszweck)
postingKey	int	0	Transfer Key (Textschlüssel, z.B. Spendenzahlung = 69)
currency	Currency	Currency.EUR	Currency (Währung)
executionDate	DateTime?	null	Execution date (Ausführungsdatum)

Overload 3
Description: Creates a payload for exchange of bank/payment contact data

Parameter name	Type	Default	Description
authority	AuthorityType		Type of the bank transfer
name	string		Name of the receiver (Empfänger)
account	string	""	Bank account (Kontonummer)
bnc	string	""	Bank institute (Bankleitzahl)
iban	string	""	IBAN
bic	string	""	BIC
reason	string	""	Reason (Verwendungszweck)

Overload 4
Description: Generic constructor used by overload 1 and 2.

Parameter name	Type	Default	Description
authority	AuthorityType		Type of the bank transfer
name	string		Name of the receiver (Empfänger)
account	string		Bank account (Kontonummer)
bnc	string		Bank institute (Bankleitzahl)
iban	string		IBAN
bic	string		BIC
amount	decimal		Amount (Betrag)
periodicTimeunit	string	""	Unit of intervall for payment ('M' = monthly, 'W' = weekly)
periodicTimeunitRotation	int	0	Intervall for payment. This value is combined with 'periodicTimeunit'
periodicFirstExecutionDate	DateTime?	null	Date of first periodic execution
periodicLastExecutionDate	DateTime?	null	Date of last periodic execution
creditorId	string	""	Creditor id (Gläubiger ID)
mandateId	string	""	Manadate id (Mandatsreferenz)
dateOfSignature	DateTime?	null	Signature date (Erteilungsdatum des Mandats)
reason	string	""	Reason (Verwendungszweck)
postingKey	int	0	Transfer Key (Textschlüssel, z.B. Spendenzahlung = 69)
sepaReference	string	""	SEPA reference (SEPA-Referenz)
currency	Currency	Currency.EUR	Currency (Währung)
executionDate	DateTime?	null	Execution date (Ausführungsdatum)
internalMode	int	0	Only used for internal state handdling

Good to know

BezahlCode is a format which competes with the GiroCode. Both can be used for banking purposes but GiroCode is a little more common and newer. Nevertheless BezahlCode has some more features like periodic transfer and debits. So before choose one of both, check which one fits your needs and which one is better supported by your users and their QR code scanner apps.

3.2 Bitcoin Payment Address

Classname/Classfile: BitcoinAddress / PayloadGenerator.cs

When to use?

Use this payload to share Bitcoin addresses or initiate Bitcoin payments.

How to use it - simple way

BitcoinAddress generator = new PayloadGenerator.BitcoinAddress("175tWpb8K1S7NmH4Zx6rewF9WQrcZv245W", 1.5d);
string payload = generator.ToString();

QRCodeGenerator qrGenerator = new QRCodeGenerator();
QRCodeData qrCodeData = qrGenerator.CreateQrCode(payload, QRCodeGenerator.ECCLevel.Q);
QRCode qrCode = new QRCode(qrCodeData);
var qrCodeAsBitmap = qrCode.GetGraphic(20);

Parameter table

There is 1 overload:

Overload 1
Description: Creates a Bitcoin address with or without amount to transfer and message.

Parameter name	Type	Default	Description
address	string		Bitcoin address of the payment receiver
amount	double?		Amount of Bitcoins to transfer
label	string	null	Reference label
message	string	null	Referece text aka message

Good to know

If you want to share only the Bitcoin address without any amount of Bitcoins, set the variable amount to null.

3.3 Bookmark

3.4 Calendar events (iCal/vEvent)

3.5 ContactData (MeCard/vCard)

3.6 Geolocation

3.7 Girocode

3.8 Mail

3.9 MMS

3.10 Monero address/payment

3.11 One-Time-Password

3.12 Phonenumber

3.13 Shadowsocks configuration

3.14 Skype call

3.15 SMS

3.16 SwissQrCode (ISO-20022)

3.17 URL

3.18 WhatsAppMessage

3.19 WiFi

4. Development of own payload types