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 dataCaptureContext = DataCaptureContext.forLicenseKey(SCANDIT_LICENSE_KEY); Camera camera = Camera.getDefaultCamera(); camera.applySettings(BarcodeCapture.createRecommendedCameraSettings()); dataCaptureContext.setFrameSource(camera); camera.switchToDesiredState(FrameSourceState.ON); BarcodeCaptureSettings barcodeCaptureSettings = new BarcodeCaptureSettings(); BarcodeCapture barcodeCapture = BarcodeCapture.forDataCaptureContext(dataCaptureContext, barcodeCaptureSettings); Parser parser = Parser.forFormat(dataCaptureContext, ParserDataFormat.SWISS_QR); Map<String, Object> options = new HashMap<>(); options.put("minimalVersion", 100); parser.setOptions(options);
Then, you need to implement BarcodeCaptureListener:
class MyBarcodeCaptureListener implements BarcodeCaptureListener { @Override public void onBarcodeScanned( @NonNull BarcodeCapture barcodeCapture, @NonNull BarcodeCaptureSession session, @NonNull FrameData frameData ) { if (session.getNewlyRecognizedBarcode() == null) return; Barcode barcode = session.getNewlyRecognizedBarcode(); String data = barcode.getData(); try { ParsedData parsedData = parser.parseString(data); /* * Extract the fields relevant to your use case. Below, for example, we extract a creditor's name, * which has the type String, and a due date, which is represented as a map with keys * "year", "month", "day". */ String creditorName = (String) parsedData.getFieldsByName().get("QRCH/CdtrInf/Cdtr/Name").getParsed(); Map<String, Object> dueDate = (Map<String, Object>) parsedData.getFieldsByName().get("QRCH/CcyAmtDate/ReqdExctnDt").getParsed(); int year = dueDate.get("year"); int month = dueDate.get("month"); int day = dueDate.get("day"); // Do something with the extracted fields. } catch (RuntimeException e) { message = e.getMessage(); } } // Other callbacks omitted for brevity. }
Finally, add the listener to the mode to receive scan results:
barcodeCapture.addListener(new MyBarcodeCaptureListener());
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:
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”).
Query ParsedField.warnings for the list of non-critical errors encountered for a given field. You can access all the fields with encountered errors by calling ParsedData.fieldsWithIssues.