Swiss QR

Overview

The parser supports the 1.0, 2.0 and the 2.1 versions of the Swiss QR ISO 20022 standard. For the complete documentation of the standard please refer to the official website.

Sample usage for SwissQr parser and Barcode Capture

First, you need to create a DataCaptureContext, access a Camera and create SwissQr parser:

DataCaptureContext context = DataCaptureContext.ForLicenseKey(SCANDIT_LICENSE_KEY);
Camera camera = Camera.GetDefaultCamera();
camera?.ApplySettingsAsync(BarcodeCapture.RecommendedCameraSettings);
context.SetFrameSourceAsync(camera);
camera?.SwitchToDesiredStateAsync(FrameSourceState.On);

BarcodeCaptureSettings barcodeCaptureSettings = BarcodeCaptureSettings.Create();
BarcodeCapture barcodeCapture = BarcodeCapture.Create(context, barcodeCaptureSettings);

Parser parser = Parser.Create(this.dataCaptureContext, ParserDataFormat.SwissQr);
parser.SetOptions(new Dictionary<string, object>() { { "minimalVersion", 100 } });

Then, you need to implement IBarcodeCaptureListener:

public void OnBarcodeScanned(BarcodeCapture barcodeCapture, BarcodeCaptureSession session, IFrameData frameData)
{
    var barcode = session?.NewlyRecognizedBarcode;

    if (barcode == null)
    {
        return;
    }
    try
    {
        ParsedData parsedData = parser.ParseString(barcode.Data);
        /*
         * Extract the fields relevant to your use case. Below, for example, we extract a batch/lot number,
         * which has the type String, and an expiry date, which is represented as a map with keys
         * "year", "month", "day".
         */
        string creditorName = parsedData.FieldsByName["QRCH/CdtrInf/Cdtr/Name"].Parsed.ToString();

        var dictionary = (NSDictionary)parsedData.FieldsByName["QRCH/CcyAmtDate/ReqdExctnDt"].Parsed;

        int year = ((NSNumber)dictionary["year"]).Int32Value;
        int month = ((NSNumber)dictionary["month"]).Int32Value;
        int day = ((NSNumber)dictionary["day"]).Int32Value;

        // Do something with the extracted fields.
    }
    catch (ArgumentException e)
    {
        // Handle the parser errors
    }
}

Finally, add the listener to the mode to receive scan results:

barcodeCapture.AddListener(this);

For details, go to the API docs.

Example

Parsing following, SwissQr version 1, code (without quotes):

"SPC\r\n0100\r\n1\r\nCH6812345678901234567\r\nScandit AG\r\nLimmatstrasse\r\n73\r\n8005\r\nZuerich\r\nCH\r\n\r\n\r\n\r\n\r\n\r\n\r\n1234.00\r\nCHF\r\n2020-01-01\r\n\r\n\r\n\r\n\r\n\r\n\r\nNON\r\n\r\ntest code\r\nAC:Alternative scheme data first\r\nAC:Alternative scheme data second"

will result in following JSON output:

[
 {
   "name" : "QRCH/Header/QRType",
   "parsed" : "SPC",
   "rawString" : "SPC"
},
{
   "name" : "QRCH/Header/Version",
   "parsed" : "0100",
   "rawString" : "0100"
},
{
   "name" : "QRCH/Header/Coding",
   "parsed" : 1,
   "rawString" : "1"
},
{
   "name" : "QRCH/CdtrInf/IBAN",
   "parsed" : "CH6812345678901234567",
   "rawString" : "CH6812345678901234567"
},
{
   "name" : "QRCH/CdtrInf/Cdtr/Name",
   "parsed" : "Scandit AG",
   "rawString" : "Scandit AG"
},
{
   "name" : "QRCH/CdtrInf/Cdtr/StrtNm",
   "parsed" : "Limmatstrasse",
   "rawString" : "Limmatstrasse"
},
{
   "name" : "QRCH/CdtrInf/Cdtr/BldgNb",
   "parsed" : "73",
   "rawString" : "73"
},
{
   "name" : "QRCH/CdtrInf/Cdtr/PstCd",
   "parsed" : "8005",
   "rawString" : "8005"
},
{
   "name" : "QRCH/CdtrInf/Cdtr/TwnNm",
   "parsed" : "Zuerich",
   "rawString" : "Zuerich"
},
{
   "name" : "QRCH/CdtrInf/Cdtr/Ctry",
   "parsed" : "CH",
   "rawString" : "CH"
},
{
   "name" : "QRCH/UltmtCdtr/Name",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/UltmtCdtr/StrtNm",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/UltmtCdtr/BldgNb",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/UltmtCdtr/PstCd",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/UltmtCdtr/TwnNm",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/UltmtCdtr/Ctry",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/CcyAmtDate/Amt",
   "parsed" : "1234.00",
   "rawString" : "1234.00"
},
{
   "name" : "QRCH/CcyAmtDate/Ccy",
   "parsed" : "CHF",
   "rawString" : "CHF"
},
{
   "name" : "QRCH/CcyAmtDate/ReqdExctnDt",
   "parsed" : {
      "day" : 1,
      "month" : 1,
      "year" : 2020
   },
   "rawString" : "2020-01-01"
},
{
   "name" : "QRCH/UltmtDbtr/Name",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/UltmtDbtr/StrtNm",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/UltmtDbtr/BldgNb",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/UltmtDbtr/PstCd",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/UltmtDbtr/TwnNm",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/UltmtDbtr/Ctry",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/RmtInf/Tp",
   "parsed" : "NON",
   "rawString" : "NON"
},
{
   "name" : "QRCH/RmtInf/Ref",
   "parsed" : "",
   "rawString" : ""
},
{
   "name" : "QRCH/RmtInf/Ustrd",
   "parsed" : "test code",
   "rawString" : "test code"
},
{
   "name" : "QRCH/AltPmtInf/AltPmt/1",
   "parsed" : "AC:Alternative scheme data first",
   "rawString" : "AC:Alternative scheme data first"
},
{
   "name" : "QRCH/AltPmtInf/AltPmt/2",
   "parsed" : "AC:Alternative scheme data second",
   "rawString" : "AC:Alternative scheme data second"
}
]

Exposed fields for Version 1.0

The exposed fields correspond one-to-one with the fields defined in the specs. The full list is given below:

Element Name

Meaning

Always Present

May be empty

Parsed Content

QRCH/Header/QRType

Indicator for Swiss QR Code, always ‘SPC’

yes

no

QRCH/Header/Version

Version string, ‘0100’ for v1.0

yes

no

QRCH/Header/Coding

Character set code, always 1

yes

no

parsed Integer

QRCH/CdtrInf/IBAN

IBAN (string of 21 characters)

yes

no

QRCH/CdtrInf/Cdtr/Name

Creditor’s name

yes

no

QRCH/CdtrInf/Cdtr/StrtNm

Creditor’s street name

yes

yes

QRCH/CdtrInf/Cdtr/BldgNb

Creditor’s house number

yes

yes

QRCH/CdtrInf/Cdtr/PstCd

Creditor’s postal code

yes

no

QRCH/CdtrInf/Cdtr/TwnNm

Creditor’s city

yes

no

QRCH/CdtrInf/Cdtr/Ctry

Creditor’s country (2 digit ISO 3166-1)

yes

no

QRCH/UltmtCdtr/Name

Ultimate Creditor’s name

yes

yes (but only if all other QRCH/UltmtCdtr/* fields are empty)

QRCH/UltmtCdtr/StrtNm

Ultimate Creditor’s street name

yes

yes

QRCH/UltmtCdtr/BldgNb

Ultimate Creditor’s house number

yes

yes

QRCH/UltmtCdtr/PstCd

Ultimate Creditor’s postal code

yes

yes (but only if all other QRCH/UltmtCdtr/* fields are empty)

QRCH/UltmtCdtr/TwnNm

Ultimate Creditor’s city

yes

yes (but only if all other QRCH/UltmtCdtr/* fields are empty)

QRCH/UltmtCdtr/Ctry

Ultimate Creditor’s country (2 digit ISO 3166-1)

yes

yes (but only if all other QRCH/UltmtCdtr/* fields are empty)

QRCH/CcyAmtDate/Amt

Payment amount

yes

yes

QRCH/CcyAmtDate/Ccy

Currency (‘CHF’ or ‘EUR’)

yes

no

QRCH/CcyAmtDate/ReqdExctnDt

Due date

yes

yes

key/value pairs:

  • ‘year’ : YYYY,

  • ‘month’ : MM,

  • ‘day’ : DD

with YYYY, MM, DD integers

QRCH/UltmtDbtr/Name

Ultimate Debitor’s name

yes

yes (but only if all other QRCH/UltmtDbtr/* fields are empty)

QRCH/UltmtDbtr/StrtNm

Ultimate Debitor’s street name

yes

yes

QRCH/UltmtDbtr/BldgNb

Ultimate Debitor’s house number

yes

yes

QRCH/UltmtDbtr/PstCd

Ultimate Debitor’s postal code

yes

yes (but only if all other QRCH/UltmtDbtr/* fields are empty)

QRCH/UltmtDbtr/TwnNm

Ultimate Debitor’s city

yes

yes (but only if all other QRCH/UltmtDbtr/* fields are empty)

QRCH/UltmtDbtr/Ctry

Ultimate Debitor’s country (2 digit ISO 3166-1)

yes

yes (but only if all other QRCH/UltmtDbtr/* fields are empty)

QRCH/RmtInf/Tp

Reference type (QRR for QR reference, SCOR for Creditor Reference, NON wihtout reference)

yes

no

QRCH/RmtInf/Ref

Reference number

yes

yes

QRCH/AltPmtInf/AltPmt/1

Additional scheme parameters (first)

no

yes

QRCH/AltPmtInf/AltPmt/1

Additional scheme parameters (second)

no

yes

Exposed fields for Version 2.0 and 2.1

The exposed fields correspond one-to-one with the fields defined in the specs (link). The full list is given below:

Element Name

Meaning

Always Present

May be empty

Parsed Content

QRCH/Header/QRType

Indicator for Swiss QR Code, always ‘SPC’

yes

no

QRCH/Header/Version

Version string, ‘0200’ for v2.0 and ‘0210 for v2.1

yes

no

QRCH/Header/Coding

Character set code, always 1

yes

no

parsed Integer

QRCH/CdtrInf/IBAN

IBAN (string of 21 characters)

yes

no

QRCH/CdtrInf/Cdtr/AdrTp

Address type

yes

yes

S for structured address, K for combined address

QRCH/CdtrInf/Cdtr/Name

Creditor’s name

yes

no

QRCH/CdtrInf/Cdtr/StrtNmOrAdrLine1

Creditor’s street name

yes

yes for structured address, no for combined address

QRCH/CdtrInf/Cdtr/BldgNbOrAdrLine2

Creditor’s house number

yes

yes for structured address, no for combined address

QRCH/CdtrInf/Cdtr/PstCd

Creditor’s postal code

yes

no for structured address, yes for combined address

QRCH/CdtrInf/Cdtr/TwnNm

Creditor’s city

yes

no for structured address, yes for combined address

QRCH/CdtrInf/Cdtr/Ctry

Creditor’s country (2 digit ISO 3166-1)

yes

no

QRCH/UltmtCdtr/AdrTp

Ultimate Creditor’s address type

yes

yes

S for structured address, K for combined address

QRCH/UltmtCdtr/Name

Ultimate Creditor’s name

yes

yes (but only if all other QRCH/UltmtCdtr/* fields are empty)

QRCH/UltmtCdtr/StrtNmOrAdrLine1

Ultimate Creditor’s street name

yes

yes for structured address, no for combined address

QRCH/UltmtCdtr/BldgNbOrAdrLine2

Ultimate Creditor’s house number

yes

yes for structured address, no for combined address

QRCH/UltmtCdtr/PstCd

Ultimate Creditor’s postal code

yes

yes (but only if all other QRCH/UltmtCdtr/* fields are empty)

QRCH/UltmtCdtr/TwnNm

Ultimate Creditor’s city

yes

yes (but only if all other QRCH/UltmtCdtr/* fields are empty)

QRCH/UltmtCdtr/Ctry

Ultimate Creditor’s country (2 digit ISO 3166-1)

yes

yes (but only if all other QRCH/UltmtCdtr/* fields are empty)

QRCH/CcyAmtDate/Amt

Payment amount

yes

yes

QRCH/CcyAmtDate/Ccy

Currency (‘CHF’ or ‘EUR’)

yes

no

QRCH/UltmtDbtr/AdrTp

Ultimate Debitor’s address type

yes

yes

S for structured address, K for combined address

QRCH/UltmtDbtr/Name

Ultimate Debitor’s name

yes

yes (but only if all other QRCH/UltmtDbtr/* fields are empty)

QRCH/UltmtDbtr/StrtNmOrAdrLine1

Ultimate Debitor’s street name

yes

yes for structured address, no for combined address

QRCH/UltmtDbtr/BldgNbOrAdrLine2

Ultimate Debitor’s house number

yes

yes for structured address, no for combined address

QRCH/UltmtDbtr/PstCd

Ultimate Debitor’s postal code

yes

yes (but only if all other QRCH/UltmtDbtr/* fields are empty)

QRCH/UltmtDbtr/TwnNm

Ultimate Debitor’s city

yes

yes (but only if all other QRCH/UltmtDbtr/* fields are empty)

QRCH/UltmtDbtr/Ctry

Ultimate Debitor’s country (2 digit ISO 3166-1)

yes

yes (but only if all other QRCH/UltmtDbtr/* fields are empty)

QRCH/RmtInf/Tp

Reference type (QRR for QR reference, SCOR for Creditor Reference, NON wihtout reference)

yes

no

QRCH/RmtInf/Ref

Reference number

yes

yes

QRCH/RmtInf/AddInf/Ustrd

Unstructured message

yes

yes

QRCH/RmtInf/AddInf/Trailer

Unambigous information for the end of payment data, always ‘EPD’

yes

no

QRCH/RmtInf/AddInf/StrdBkgInf

Bill information

yes

yes

QRCH/AltPmtInf/AltPmt/1

Additional scheme parameters (first)

no

yes

QRCH/AltPmtInf/AltPmt/2

Additional scheme parameters (second)

no

yes

Parser Options

The parser can be configured by providing a JSON string containing key / value pairs. The following configuration options are available:

Key

Value Type

Description

minimalVersion

Int

Sets minimal version of Swiss Payment Standard that will be parsed. Available options are: 100 (1.0 version), 200 (2.0 version) and 210 (2.1 version). By default it is 200.

strictMode

boolean

Controls the strictness of the parser. When strictMode is set to false, parsing continues for non-critical errors (missing required field, fields containing incorrect characters, invalid separator or character etc.). The encountered problems can be queried via the issues property. By default option is set to true.

Strict Mode

By default the parser operates in strict mode - that means parsing is going to fail whenever the parsed code deviates from the standard.

When strictMode is set to false, parsing continues for the following non-critical errors:

  • A mandatory field is empty or missing;

  • The code mixes CR + LF and LF separators between elements;

  • QRCH/CcyAmtDate/Ccy (currency) contains non-alphanumeric characters or is of incorrect length;

  • QRCH/CdtrInf/IBAN (IBAN) contains whitespace characters;

  • PstCd (postal code) and/or TwnNm (town) are present for an address defined as combined (“K”).