Advanced usage Payload generators

Introduction to the "Payload Generator"
Overview of the different payload types
Usage of the payload generators
3.1 BezahlCode
3.2 Crypto Payment Address (e.g. Bitcoin, Litecoin, ...)
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 Russia Payment Order
3.14 Shadowsocks configuration
3.15 Skype call
3.16 Slovenian QR Code for UPN QR Forms
3.17 SMS
3.18 SwissQrCode (ISO-20022)
3.19 URL
3.20 WhatsAppMessage
3.21 WiFi
Development of own payload types

1. Introduction to the "Payload Generator"

The payload generator is one of 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
Bitcoin(LikeCryptoCurrency)Address	Starts crypto currency 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
SlovenianUpnQr	Used for creation of Slovenian QR Code for UPN QR Forms (UPN = Univerzalni plačilni nalog - Universal Payment Order).	Technical description, Advice for programmers
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. Is part of the "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 like) Crypto Currency Payment Address

Classname/Classfile: BitcoinAddress|BitcoinCashAddress|LitecoinAddress / PayloadGenerator.cs

When to use?

Use this payload to share Bitcoin/Bitcoin Cash/Litecoin addresses or initiate payments in one of those currencies.

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 crypto currency address without any amount of coins, set the variable amount to null. Replace "Bitcoin" by "BitcoinCash" or "Litecoin" to generate payloads for those currencies.

3.3 Bookmark

Classname/Classfile: Bookmark / PayloadGenerator.cs

When to use?

Use this payload, when you want to place a bookmark in the user's default webbrowser.

How to use it - simple way

Bookmark generator = new Bookmark("http://code-bude.net", "Blog of QRCoder's father");
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 bookmark payload including the bookmark title.

Parameter name	Type	Default	Description
url	string		Url of the bookmark
title	string		Title of the bookmark

Good to know

n/a

3.4 Calendar events (iCal/vEvent)

Classname/Classfile: CalendarEvent / PayloadGenerator.cs

When to use?

Use this payload to place an event to the user's calendar application.

How to use it - simple way

CalendarEvent generator = new CalendarEvent("Birthday party", "Join QRCoder's fourth birthday!", "51.26118,6.6717", new DateTime(2017,10,13), new DateTime(2017,10,13), true);
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 2 overloads:

Overload 1
Description: Creates an calendar event.

Parameter name	Type	Default	Description
subject	string		Subject/title of the calender event
description	string		Description of the event
location	string		Location (lat:long or address) of the event
start	DateTime		Start time of the event
end	DateTime		End time of the event
allDayEvent	bool		Is it a full day event?
encoding	EventEncoding	EventEncoding.Universal	Type of encoding (universal or iCal)

Overload 2
Description: Creates an calendar event.

Parameter name	Type	Default	Description
subject	string		Subject/title of the calender event
description	string		Description of the event
location	string		Location (lat:long or address) of the event
start	DateTimeOffset		Start time of the event incl. offset in relation to UTC
end	DateTimeOffset		End time of the event incl. offset in relation to UTC
allDayEvent	bool		Is it a full day event?
encoding	EventEncoding	EventEncoding.Universal	Type of encoding (universal or iCal)

Good to know

The parameters description and location are optional. They can be set to null or string.Empty. If you want to place an event to Apple users you should use iCal instead of Universal as encoding.

3.5 ContactData (MeCard/vCard)

Classname/Classfile: ContactData / PayloadGenerator.cs

When to use?

Use it, when you want to share contact data/business cards. A QR code with this payload type will add the contact data to the user's address book.

How to use it - simple way

ContactData generator = new ContactData(ContactData.ContactOutputType.VCard3, "John", "Doe");
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: Generates contact data payload in different formats.

Parameter name	Type	Default	Description
outputType	ContactOutputType		Payload output type
firstname	string		The firstname
lastname	string		The lastname
nickname	string	null	The displayname
phone	string	null	Normal phone number
mobilePhone	string	null	Mobile phone
workPhone	string	null	Office phone number
email	string	null	E-Mail address
birthday	DateTime?	null	Birthday
website	string	null	Website / Homepage
street	string	null	Street
houseNumber	string	null	Housenumber
city	string	null	City
zipCode	string	null	Zip code
country	string	null	Country
note	string	null	Memo text / notes
stateRegion	string	null	State / Region
addressOrder	AddressOrder	AddressOrder.Default	enum to define address order (see below)
org	string	null	Organization/Company
orgTitle	string	null	Organization/Company title

Good to know

Via the parameter outputType you can choose between different formats. Supported formats are: vCard 2.1, vCard 3.0, vCard 4.0 and MeCard. Choose the format which fits your needs. Right now vCard 3.0 is the most used format.

The addressOrder enum specifies in which format the address is rendered. The two options are:

Default
The address format used in European countries and others.
Sample

John Doe
Königsallee 1
40210 Düsseldorf
Germany
Reversed
The address format used in North America and others.
Sample

John Doe
123 Fake St.
Cleveland, OH, 12345
USA

3.6 Geolocation

Classname/Classfile: Geolocation / PayloadGenerator.cs

When to use?

Use this payload type when you want to share a location. You can choose between the geo-format and Google Maps links.

How to use it - simple way

Geolocation generator = new Geolocation("51.26118", "6.6717");
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: The payload encodes a (geo-)location by its coordinates.

Parameter name	Type	Default	Description
latitude	string		Latitude with . as splitter
longitude	string		Longitude with . as splitter
encoding	GeolocationEncoding	GeolocationEncoding.GEO	Encoding type - GEO or GoogleMaps

Good to know

If you use the geo-format the QR scanner app must support this tag. Most scanners do so. But if you want to be 100% on the safe side, choose Google Maps format because this generates a Google Maps (web-)link which can be interpreted by nearly any QR code scanner.

3.7 Girocode

Classname/Classfile: Girocode / PayloadGenerator.cs

When to use?

Use this payload type if you want to share payment contact information and/or bank transfer data. The Girocode is an European standard and supports SEPA payments.

How to use it - simple way

var payload = new Girocode("DE33100205000001194700", "BFSWDE33BER", "Wikimedia", 1337.99m);

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

Parameter table

There is 1 overload:

Overload 1
Description: Generates the Girocode payload with different options.

Parameter name	Type	Default	Description
iban	string		Account number of the Beneficiary. Only IBAN is allowed.
bic	string		BIC of the Beneficiary Bank.
name	string		Name of the Beneficiary.
amount	decimal		Amount of the Credit Transfer in Euro. (Amount must be more than 0.01 and less than 999999999.99)
remittanceInformation	string	""	Remittance Information (Purpose-/reference text). (optional)
typeOfRemittance	TypeOfRemittance	TypeOfRemittance. Unstructured	Type of remittance information. Either structured (e.g. ISO 11649 RF Creditor Reference) and max. 35 chars or unstructured and max. 140 chars.
purposeOfCreditTransfer	string	""	Purpose of the Credit Transfer (optional)
messageToGirocodeUser	string	""	Beneficiary to originator information. (optional)
version	GirocodeVersion	GirocodeVersion. Version1	Girocode version. Either 001 or 002. Default: 001.
encoding	GirocodeEncoding	GirocodeEncoding. ISO_8859_1	Encoding of the Girocode payload. Default: ISO-8859-1

Good to know

Important: As per official specification QR codes with Girocode payloads have to be generated with ECC-Level M (15%). The necessary EccLevel is already set in the payload. Therefore, please always pass the entire payload object to the CreateQrCode function instead of calling ToString().

Girocode competes (atleast for German-speaking countries) with the Bezahlcode. Even if Girocode has less features, it is more common than Bezahlcode. So choose the right payload type in respect of your users and the features you want to use.

3.8 Mail

Classname/Classfile: Mail / PayloadGenerator.cs

When to use?

Use it when you want to prepare/compose an email. Once scanned the code opens the default mail client with the given information like receiver, subject and message.

How to use it - simple way

Mail generator = new Mail("[email protected]", "Look at this!", "Hi John, have a look at this QRCoder library!");
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 one overload:

Overload 1
Description: Creates a new mail with optional subject and body/message.

Parameter name	Type	Default	Description
mailReceiver	string	null	Receiver's email address
subject	string	null	Subject line of the email
message	string	null	Message content of the email
encoding	MailEncoding	MailEncoding.MAILTO	Payload encoding type. Choose dependent on your QR Code scanner app.

Good to know

n/a

3.9 MMS

Classname/Classfile: MMS / PayloadGenerator.cs

When to use?

Use it when you want to compose a MMS (message). You can choose if you want to prepare the message or just let the QR code open the messaging app with the correct phonenumber.

How to use it - simple way

MMS generator = new MMS("+491701234567", "Hi John, have a look at this QRCoder library!");
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 2 overloads:

Overload 1
Description: Generates a new MMS for the given contact.

Parameter name	Type	Default	Description
number	string		Receiver phone number
encoding	MMSEncoding	MMSEncoding.MMS	Encoding type

Overload 2
Description: (Pre-)composes a new MMS for the given contact with the given message (=subject).

Parameter name	Type	Default	Description
number	string		Receiver phone number
subject	string		Text of the MMS
encoding	MMSEncoding	MMSEncoding.MMS	Encoding type

Good to know

This payload type supports (as some of the other payload types, too) different output formats. In most cases/regions you should use the MMSEncoding.MMS-type.

3.10 Monero address/payment

Classname/Classfile: MoneroTransaction / PayloadGenerator.cs

When to use?

This payload opens the user's Monero client/app and prefills its dialog with the given data. Either you pass only the Monero address or you add complete payment/transaction details.

How to use it - simple way

MoneroTransaction generator = new MoneroTransaction("46BeWrHpwXmHDpDEUmZBWZfoQpdc6HaERCNmx1pEYL2rAcuwufPN9rXHHtyUA4QVy66qeFQkn6sfK8aHYjA3jk3o1Bv16em");
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: Generates a Monero payload.

Parameter name	Type	Default	Description
address	string		Receiver's monero address
txAmount	float?	null	Amount to transfer
txPaymentId	string	null	Payment id
recipientName	string	null	Receipient's name
txDescription	string	null	Reference text / payment description

Good to know

n/a

3.11 One-Time-Password

Classname/Classfile: OneTimePassword / PayloadGenerator.cs

When to use?

This payload generates a one-time-password QR code which is used for credential-exchange and authentification. You may use it in combination with the Google Authenticator.

How to use it - simple way

OneTimePassword generator = new OneTimePassword()
{
	Secret = "pwq6 5q55",
	Issuer = "Google",
	Label = "[email protected]",
};
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 0 special overloads. As can be seen in the example above these generator takes it values via properties.

Property name	Type	Default	Description
Type	OneTimePassword AuthType	OneTimePasswordAuth Type.TOTP	Type of the one-time-password. Either TOTP or HOTP
Algorithm	OoneTimePassword AuthAlgorithm	OoneTimePasswordAuth Algorithm.SHA1	Algorith of the one-time-password. Either SHA1, SHA256 or SHA512
Issuer	string		The issuer's name
Secret	string		The Base32 encoded secret key
Label	string		The label
Digits	int	6	Number of digits
Counter	int?	null	Shall a counter be used?
Period	int?	30	Valid period

Good to know

The payload generator builds the correct payload for you, but it can't/doesn't calculate the TOTP/HOTP secret for you.

3.12 Phonenumber

Classname/Classfile: PhoneNumber / PayloadGenerator.cs

When to use?

Use it, when you wan't to share a phonenumber or when you want to use the QR code as CTA (call-to-action). Once scanned, the code opens the dialer app on the phone.

How to use it - simple way

PhoneNumber generator = new PhoneNumber("+491701234567");
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: Generates a phone call payload.

Parameter name	Type	Default	Description
number	string		Phonenumber of the receiver

Good to know

There is no right or wrong formatting of the given phonenumber. Type the number in this way, you would type it into your phone's dialer.

3.13 RussiaPaymentOrder

Classname/Classfile: RussiaPaymentOrder / PayloadGenerator.cs

When to use?

Use it to generate QR codes for payments in Russia that are compliant to the standard ГОСТ Р 56042-2014.

How to use it - simple way

var account = "40702810138250123017";
var bic = "044525225";
var bankName = "ОАО \"БАНК\"";
var name = "ООО «Три кита»";
var correspAcc = "30101810965770000413";
var generator = new PayloadGenerator.RussiaPaymentOrder(name, account, bankName, bic, correspAcc);
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(3);

Parameter table

There is 1 overload:

Overload 1
Description: Generates a RussiaPaymentOrder configuration QR code payload.

Parameter name	Type	Default	Description
name	string		Name of the payee (Наименование получателя платежа)
personalAcc	string		Beneficiary account number (Номер счета получателя платежа)
bankName	string		Name of the beneficiary's bank (Наименование банка получателя платежа)
BIC	string		BIC (БИК)
correspAcc	string	null	Box number / account payee's bank (Номер кор./сч. банка получателя платежа)
optionalFields	OptionalFields	null	Optional additional fields/information
characterSet	CharacterSets	CharacterSets.utf_8	Encoding of the payload string

Good to know

If CharacterSets was set to windows-1251 or koi8-r you should use ToBytes() instead of ToString() and pass the byte-array directly to CreateQrCode()!
The maximum length of a RussiaPaymentOrder is 300 byte as defined by the offical standard. Thus it isn't possible to use all additional fields at the same time.

3.14 Shadowsocks configuration

Classname/Classfile: ShadowSocksConfig / PayloadGenerator.cs

When to use?

Use it to share ShadowSocks (Proxy) configurations. When scanned, the QR scanner app should start the ShadowSocks with the given configuration.

How to use it - simple way

ShadowSocksConfig generator = new ShadowSocksConfig("45.78.47.87", 443, "laozhang", ShadowSocksConfig.Method.Aes256Cb);
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: Generates a ShadowSocks configuration QR code payload.

Parameter name	Type	Default	Description
hostname	string		Hostname of the ShadowSocks proxy
port	int		Port of the ShadowSocks proxy
password	string		Password of the SS proxy
method	Method		Encryption type
tag	string	null	Optional tag line

Good to know

The value of port must be in the range within 1 and 65535. The tag parameter is optional.

3.15 Skype call

Classname/Classfile: SkypeCall / PayloadGenerator.cs

When to use?

Use it when you want to initiate Skype calls. When scanned, the QR scanner app opens skype and calls the user given to the payload generator.

How to use it - simple way

SkypeCall generator = new SkypeCall("johndoe");
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 skype call action payload.

Parameter name	Type	Default	Description
skypeUsername	string		Skype username which will be called

Good to know

n/a

3.16 SlovenianUpnQr

Classname/Classfile: SlovenianUpnQr / PayloadGenerator.cs

When to use?

Used for creation of Slovenian QR Code for UPN QR Forms (UPN = Univerzalni plačilni nalog - Universal Payment Order)

How to use it - simple way

var payload = new PayloadGenerator.SlovenianUpnQr(payerName, payerAddress, payerPlace, 
                                    recipientName, recipientAddress, recipientPlace, 
                                    recipientIban, 
                                    description, 
                                    amount, 
                                    recipientSiModel, recipientSiReference, 
                                    code);
//or if you need requested date of debitor’s payment (payment deadline) included
var payload = new PayloadGenerator.SlovenianUpnQr(payerName, payerAddress, payerPlace, 
                                    recipientName, recipientAddress, recipientPlace, 
                                    recipientIban, 
                                    description, 
                                    amount, 
                                    deadline,
                                    recipientSiModel, recipientSiReference, 
                                    code);

QRCodeData qrCodeData = qrGenerator.CreateQrCode(payload);

QRCode qrCode = new QRCode(qrCodeData);
Bitmap qrCodeImage = qrCode.GetGraphic(5);
qrCodeImage.Save(@"GeneratedQRCode.bmp");

Parameter table

Parameter name	Type	Max Length	Default	Description
payerName	string	33		Debitor (payer) name
payerAddress	string	33		Debitor (payer) address (Street name and house number)
payerPlace	string	33		Debitor (payer) place (Postal code and name)
recipientName	string	33		Creditor (payee) name
recipientAddress	string	33		Creditor (payee) address (Street name and house number)
recipientPlace	string	33		Creditor (payee) place (Postal code and name)
recipientIban	string	34		Creditor's IBAN
description	string	42		Description/Comment
amount	double			Amount (in EUR)
deadline	DateTime?			Requested date of debitor's payment
recipientSiModel	string	4	SI99	SI model
recipientSiReference	string	22		SI reference
code	string	4	OTHR	Purpose of Payment Code

Good to know

Important: As per official specification Slovenian UPN QR codes have to be generated with ECC-Level M (15%), ECI Mode set to ISO8859-2, Byte mode and QR Version of 15. If you pass the Payload-class itself to the QRCoder (as shown in the last example) then you don't have to set this parameters, since the Payload-class does this automatically.

3.17 SMS

Classname/Classfile: SMS / PayloadGenerator.cs

When to use?

Use it when you want to compose a SMS (message). You can choose if you want to create the message including text or just let the QR code open the messaging app with the given phonenumber.

How to use it - simple way

SMS generator = new SMS("+491701234567", "Hi John, do you remember SMS?");
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 2 overloads:

Overload 1
Description: Generates a new SMS for the given contact.

Parameter name	Type	Default	Description
number	string		Receiver phone number
encoding	SMSEncoding	SMSEncoding.SMS	Encoding type

Overload 2
Description: (Pre-)composes a new SMS for the given contact with the given message (=subject).

Parameter name	Type	Default	Description
number	string		Receiver phone number
subject	string		Text of the SMS
encoding	SMSEncoding	SMSEncoding.SMS	Encoding type

Good to know

This payload supports different output formats. In most cases/regions you should use the SMSEncoding.SMS-type, which should work with the most scanner apps.

3.18 SwissQrCode (ISO-20022)

Classname/Classfile: SwissQRCode / PayloadGenerator.cs

When to use?

Opens a banking app for bank transfer or donations. Mostly common in Switzerland. Is part of the "QR-Rechnung" (former Einzahlungsschein). Note: Take care of the advices from the "Good to know" section.

How to use it - simple way

SwissQrCode.Contact contactGeneral = SwissQrCode.Contact.WithStructuredAddress("John Doe", "3003", "Bern", "CH", "Parlamentsgebäude", "1");
SwissQrCode.Iban iban = new SwissQrCode.Iban("CH2609000000857666015", PayloadGenerator.SwissQrCode.Iban.IbanType.QrIban);
SwissQrCode.Reference reference = new SwissQrCode.Reference(SwissQrCode.Reference.ReferenceType.QRR, "990005000000000320071012303", SwissQrCode.Reference.ReferenceTextType.QrReference);
SwissQrCode.AdditionalInformation additionalInformation = new SwissQrCode.AdditionalInformation("This is my unstructured message.", "Some bill information here...");
SwissQrCode.Currency currency = SwissQrCode.Currency.CHF;
decimal amount = 100.25m;

SwissQrCode payload = new SwissQrCode(iban, currency, contactGeneral, additionalInformation, reference, null, amount, null, null);

QRCodeGenerator qrGenerator = new QRCodeGenerator();
QRCodeData qrCodeData = qrGenerator.CreateQrCode(payload);
QRCode qrCode = new QRCode(qrCodeData);
var qrCodeAsBitmap = qrCode.GetGraphic(20, Color.Black, Color.White, (Bitmap)Bitmap.FromFile(Application.StartupPath + "\\CH-Kreuz_7mm.png"), 14, 1);

Parameter table

There is 1 overload:

Overload 1
Description: Generates a new Swiss Qr code.

Parameter name	Type	Default	Description
iban	Iban		IBAN object
currency	Currency		Currency (either EUR or CHF)
creditor	Contact		Creditor (payee) information
reference	Reference		Reference information
additionalInformation	AdditionalInformation	null	Additional information texts
debitor	Contact	null	Debitor (payer) information
amount	decimal?	null	Amount
requestedDateOfPayment	DateTime?	null	Obsolete ~~Requested date of debitor's payment~~
ultimateCreditor	Contact	null	Ultimate creditor information (use only in consultation with your bank!)
alternativeProcedure1	string	null	Optional command for alternative processing mode - line 1
alternativeProcedure2	string	null	Optional command for alternative processing mode - line 2

Good to know

Important: As per official specification Swiss QR codes have to be generated with ECC-Level M (15%). The necessary EccLevel is already set in the payload. Therefore, please always pass the entire payload object to the CreateQrCode function instead of calling ToString().
Important: As per official specification a Swiss cross logo (can be downloaded here) has to be drawn on the code with a size of ~14%. (Per spec the Swiss cross has to be 7mm per side and the Swiss Qr code should be printed with 46mm without quiet zones or 49,2mm per side with quietzones. So we get 7/(49,2/100) = 14% icon size.)

3.19 URL

Classname/Classfile: Url / PayloadGenerator.cs

When to use?

Use it to share links/websites.

How to use it - simple way

Url generator = new Url("https://github.com/codebude/QRCoder/");
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: Generates a link payload.

Parameter name	Type	Default	Description
url	string		Link url target

Good to know

If you a domain (without http:// or https://) is given, the payload generater prefixes the given url with http://.

3.20 WhatsAppMessage

Classname/Classfile: WhatsAppMessage / PayloadGenerator.cs

When to use?

Use it to share your WhatApp pre-composed WhatsAppMessages. Once scanned, the QR code opens a WhatsApp chat with the given message.

How to use it - simple way

WhatsAppMessage generator = new WhatsAppMessage("Hi John, what do you think about QR codes?");
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 2 overloads:

Overload 1
Description: Generates a new WhatsApp message.

Parameter name	Type	Default	Description
message	string		The message text

Overload 2
Description: Generates a new WhatsApp message towards a given contact.

Parameter name	Type	Default	Description
number	string		Recipient/contact number
message	string		The message text

Good to know

-/-

3.21 WiFi

Classname/Classfile: WiFi / PayloadGenerator.cs

When to use?

Use it when you want to share WiFi credentials. Good for meetings, house partys and conventions.

How to use it - simple way

WiFi generator = new WiFi("My-WiFis-Name", "s3cr3t-p4ssw0rd", WiFi.Authentication.WPA);
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: Generates WiFi login credentials.

Parameter name	Type	Default	Description
ssid	string		SSID of the WiFi network
password	string		Password of the WiFi network
authenticationMode	Authentication		Authentification mode (WEP, WPA, WPA2)
isHiddenSSID	bool	false	Set flag to true, if the WiFi network hides its SSID
escapeHexStrings	bool	true	Set flag to false, if SSID/password shouldn't be escaped, even if passed as HEX string

Good to know

Don't get confused when choosing authenticationMode-parameter. The value WiFi.Authentication.WPA also includes not only WPA but also WPA2!
For widest compatibility you may set escapeHexStrings to false, because if SSID/password are provided in HEX style ([A-F0-9] and will be escaped, the QR code may become unreadable by Apple devices. More info: )

4. Development of own payload types

Implementing your own, custom payload generator is quite easy. Simply create a new class for your custom payload and implement the QRCoder.PayloadGenerator.Payload-interface. The only method you have to implement/override is the ToString()-method.

public class HelloWorldPayload : Payload
{
    private string _name;
    public HelloWorldPayload(string name)
    {
        _name = name;
    }

    public override string ToString()
    {
        return $"Hello {_name}";
    }
}

If you have written a cool generator, feel free to send it in as PullRequest.

Crafted with ❤ by Raffael Herrmann and a bunch of cool guys.