QR Invoice REST API (2.0)
The QR Invoice REST API provides various services for creation and processing of Swiss QR Invoices. This API is available as a Cloud Service but is also available as a self-hosted solution.
Product Website
www.qr-invoice.chAPI Key
This API requires an API Key for authorization on the Cloud. You may use the following Demo API Key or request a trial API on our website: QrInvoice - Order Trial Key582c9ea9-741a-4bb6-acae-cf92f8805864
Important: Use of Demo API Key comes with a few restrictions!
Hints
- Please note, that you can retrieve JSON example documents in the «00 Example Data» section using the respective Endpoints. E.g.: https://rest.qr-invoice.cloud/v2/examples/qr-invoice/with-qr-reference
- Handle error responses correctly by checking HTTP status and read detailed error/validation message from response body
- Check all parameters
- Check out length limitation
- Consult official standards / specification if you need more detailed information regarding QR-Bill specification
Standards / Specifications
Overview of official specs www.qr-invoice.ch/dokumentation/standards-merkblaetter/QR Invoice Layers
QR Invoice Model
Product Version: 1.21-SNAPSHOT
https://rest.qr-invoice.cloud/
Output Resolution.
Desired QR Code size (in pixels). This is an alternative to Output Resolution. This is only relevant for raster graphics (e.g. PNG). Please note that it is only a hint.
If true, input gets normalized. This means strings are trimmed, special quotations replaced with ASCII ones and special characters replaced with semantically equal ones (e.g. œ -> oe)
- Generated server url
https://rest.qr-invoice.cloud/v2/swiss-qr-code
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X GET \
'https://rest.qr-invoice.cloud/v2/swiss-qr-code?format=application%2Fpdf&normalizeInput=false&qrInvoice=string&resolution=LOW_150_DPI' \
-H 'X-API-Key: YOUR_API_KEY_HERE'No response exampleOutput Resolution.
Desired QR Code size (in pixels). This is an alternative to Output Resolution. This is only relevant for raster graphics (e.g. PNG). Please note that it is only a hint.
IBAN or QR-IBAN of the creditor.
Fixed length: 21 alphanumeric characters, only IBANs with CH or LI country code permitted.
Address type
The address type is specified using a code. The following codes are defined:
"S" - structured address
"K" - combined address elements (2 lines). DEPRECATED - discontinued and no longer supported after 21.11.2025
The creditor's name or company according to the account name.
Comment: always matches the account holder
Maximum 70 characters permitted
First name (optional, if available) + last name or company name
Street/P.O. box of the creditor
Maximum 70 characters permitted, may not include any house or building number.
House number of the creditor
Maximum 16 characters permitted
Postal code of the creditor
Maximum 16 characters permitted. The postal code is always to be entered without a country code prefix.
City of the creditor
Maximum 35 characters permitted
Country of the creditor
Two-digit country code according to ISO 3166-1
Address line 1 including street and building number or P.O. Box
Maximum 70 characters permitted
The payment amount
The amount element is to be entered without leading zeroes, including decimal separators and two decimal places.
Decimal, maximum 12-digits permitted, including decimal separators. Only decimal points (".") are permitted as decimal separators.
Reference type (QR, ISO)
The following codes are permitted:
QRR – QR reference
SCOR – Creditor Reference (ISO 11649)
NON – without reference
Maximum four characters, alphanumeric
Must contain the code QRR where a QR-IBAN is used;
where the IBAN is used, either the SCOR or NON code can be entered
Reference number
Structured payment reference
The reference is either a QR reference or a Creditor Reference (ISO 11649)
Maximum 27 characters, alphanumeric;
must be filled if a QR-IBAN is used.
QR reference: 27 characters, numeric, check sum calculation according to Modulo 10 recursive (27th position of the reference)
Creditor Reference (ISO 11649): max 25 characters, alphanumeric
The element may not be filled for the NON reference type.
REST API
On the REST API automatic creation of both QRR and SCOR reference numbers can be used. To do so, wrap the reference number in curly brackets {42}. In case of the QRR, customerId can be passed as well, separated by a colon, e.g. {123456:42}, whereas 123456 is the customerId
- Generated server url
https://rest.qr-invoice.cloud/v2/swiss-qr-code
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://rest.qr-invoice.cloud/v2/swiss-qr-code?normalizeInput=false&resolution=LOW_150_DPI' \
-H 'Content-Type: application/json' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-d '{
"creditorInformation": {
"iban": "CH3908704016075473007",
"creditor": {
"addressType": "STRUCTURED",
"name": "Robert Schneider AG",
"streetName": "Rue du Lac",
"houseNumber": "1268/2/22",
"postalCode": "2501",
"city": "Biel",
"addressLine1": "Rue du Lac 1268/2/22",
"addressLine2": "2501 Biel",
"country": "CH"
}
},
"ultimateCreditor": {
"addressType": "STRUCTURED",
"name": "Robert Schneider Services Switzerland AG",
"streetName": "Rue du Lac",
"houseNumber": "1268/3/1",
"postalCode": "2501",
"city": "Biel",
"addressLine1": "Rue du Lac 1268/3/1",
"addressLine2": "2501 Biel",
"country": "CH"
},
"paymentAmountInformation": {
"amount": 199.95,
"currency": "CHF"
},
"ultimateDebtor": {
"addressType": "STRUCTURED",
"name": "Pia-Maria Rutschmann-Schnyder",
"streetName": "Grosse Marktgasse",
"houseNumber": "28",
"postalCode": "9400",
"city": "Rorschach",
"addressLine1": "Rue du Lac 1268/3/1",
"addressLine2": "2501 Biel",
"country": "CH"
},
"paymentReference": {
"referenceType": "SCOR",
"reference": "RF18539007547034",
"additionalInformation": {
"unstructuredMessage": "Bill No. 3139 for garden work and disposal of cuttings",
"billInformation": "//S1/10/10201409/11/190512/20/1400.000-53/30/106017086/31/180508/32/7.7/40/2:10;0:30",
"billInformationObject": {}
}
},
"alternativeSchemes": {
"alternativeSchemeParameters": [
"eBill/B/john.doe@example.com"
]
}
}'No response example- Generated server url
https://rest.qr-invoice.cloud/v2/swiss-qr-code/validate
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
https://rest.qr-invoice.cloud/v2/swiss-qr-code/validate \
-H 'Content-Type: multipart/form-data' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-F file=string- Generated server url
https://rest.qr-invoice.cloud/v2/swiss-qr-code/parse
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://rest.qr-invoice.cloud/v2/swiss-qr-code/parse?effortLevel=DEFAULT&expandBillInformation=false' \
-H 'Content-Type: multipart/form-data' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-F file=stringThe parsed QR Invoice structure
IBAN or QR-IBAN of the creditor.
Fixed length: 21 alphanumeric characters, only IBANs with CH or LI country code permitted.
Address type
The address type is specified using a code. The following codes are defined:
"S" - structured address
"K" - combined address elements (2 lines). DEPRECATED - discontinued and no longer supported after 21.11.2025
The creditor's name or company according to the account name.
Comment: always matches the account holder
Maximum 70 characters permitted
First name (optional, if available) + last name or company name
Street/P.O. box of the creditor
Maximum 70 characters permitted, may not include any house or building number.
House number of the creditor
Maximum 16 characters permitted
Postal code of the creditor
Maximum 16 characters permitted. The postal code is always to be entered without a country code prefix.
City of the creditor
Maximum 35 characters permitted
Country of the creditor
Two-digit country code according to ISO 3166-1
Address line 1 including street and building number or P.O. Box
Maximum 70 characters permitted
The payment amount
The amount element is to be entered without leading zeroes, including decimal separators and two decimal places.
Decimal, maximum 12-digits permitted, including decimal separators. Only decimal points (".") are permitted as decimal separators.
Reference type (QR, ISO)
The following codes are permitted:
QRR – QR reference
SCOR – Creditor Reference (ISO 11649)
NON – without reference
Maximum four characters, alphanumeric
Must contain the code QRR where a QR-IBAN is used;
where the IBAN is used, either the SCOR or NON code can be entered
Reference number
Structured payment reference
The reference is either a QR reference or a Creditor Reference (ISO 11649)
Maximum 27 characters, alphanumeric;
must be filled if a QR-IBAN is used.
QR reference: 27 characters, numeric, check sum calculation according to Modulo 10 recursive (27th position of the reference)
Creditor Reference (ISO 11649): max 25 characters, alphanumeric
The element may not be filled for the NON reference type.
REST API
On the REST API automatic creation of both QRR and SCOR reference numbers can be used. To do so, wrap the reference number in curly brackets {42}. In case of the QRR, customerId can be passed as well, separated by a colon, e.g. {123456:42}, whereas 123456 is the customerId
{ "creditorInformation": { "iban": "CH3908704016075473007", "creditor": { … } }, "ultimateCreditor": { "addressType": "STRUCTURED", "name": "Robert Schneider Services Switzerland AG", "streetName": "Rue du Lac", "houseNumber": "1268/3/1", "postalCode": "2501", "city": "Biel", "addressLine1": "Rue du Lac 1268/3/1", "addressLine2": "2501 Biel", "country": "CH" }, "paymentAmountInformation": { "amount": 199.95, "currency": "CHF" }, "ultimateDebtor": { "addressType": "STRUCTURED", "name": "Pia-Maria Rutschmann-Schnyder", "streetName": "Grosse Marktgasse", "houseNumber": "28", "postalCode": "9400", "city": "Rorschach", "addressLine1": "Rue du Lac 1268/3/1", "addressLine2": "2501 Biel", "country": "CH" }, "paymentReference": { "referenceType": "SCOR", "reference": "RF18539007547034", "additionalInformation": { … } }, "alternativeSchemes": { "alternativeSchemeParameters": [ … ], "alternativeSchemeParameterObjects": [ … ] } }
- Generated server url
https://rest.qr-invoice.cloud/v2/swiss-qr-code/parseAll
- curl
- JavaScript
- Node.js
- Python
- Java
- C#
- PHP
- Go
- Ruby
- R
- Payload
curl -i -X POST \
'https://rest.qr-invoice.cloud/v2/swiss-qr-code/parseAll?effortLevel=DEFAULT&expandBillInformation=false' \
-H 'Content-Type: multipart/form-data' \
-H 'X-API-Key: YOUR_API_KEY_HERE' \
-F file=stringThe parsed QR Invoices structure
IBAN or QR-IBAN of the creditor.
Fixed length: 21 alphanumeric characters, only IBANs with CH or LI country code permitted.
Address type
The address type is specified using a code. The following codes are defined:
"S" - structured address
"K" - combined address elements (2 lines). DEPRECATED - discontinued and no longer supported after 21.11.2025
The creditor's name or company according to the account name.
Comment: always matches the account holder
Maximum 70 characters permitted
First name (optional, if available) + last name or company name
Street/P.O. box of the creditor
Maximum 70 characters permitted, may not include any house or building number.
House number of the creditor
Maximum 16 characters permitted
Postal code of the creditor
Maximum 16 characters permitted. The postal code is always to be entered without a country code prefix.
City of the creditor
Maximum 35 characters permitted
Country of the creditor
Two-digit country code according to ISO 3166-1
Address line 1 including street and building number or P.O. Box
Maximum 70 characters permitted
The payment amount
The amount element is to be entered without leading zeroes, including decimal separators and two decimal places.
Decimal, maximum 12-digits permitted, including decimal separators. Only decimal points (".") are permitted as decimal separators.
Reference type (QR, ISO)
The following codes are permitted:
QRR – QR reference
SCOR – Creditor Reference (ISO 11649)
NON – without reference
Maximum four characters, alphanumeric
Must contain the code QRR where a QR-IBAN is used;
where the IBAN is used, either the SCOR or NON code can be entered
Reference number
Structured payment reference
The reference is either a QR reference or a Creditor Reference (ISO 11649)
Maximum 27 characters, alphanumeric;
must be filled if a QR-IBAN is used.
QR reference: 27 characters, numeric, check sum calculation according to Modulo 10 recursive (27th position of the reference)
Creditor Reference (ISO 11649): max 25 characters, alphanumeric
The element may not be filled for the NON reference type.
REST API
On the REST API automatic creation of both QRR and SCOR reference numbers can be used. To do so, wrap the reference number in curly brackets {42}. In case of the QRR, customerId can be passed as well, separated by a colon, e.g. {123456:42}, whereas 123456 is the customerId
{ "creditorInformation": { "iban": "CH3908704016075473007", "creditor": { … } }, "ultimateCreditor": { "addressType": "STRUCTURED", "name": "Robert Schneider Services Switzerland AG", "streetName": "Rue du Lac", "houseNumber": "1268/3/1", "postalCode": "2501", "city": "Biel", "addressLine1": "Rue du Lac 1268/3/1", "addressLine2": "2501 Biel", "country": "CH" }, "paymentAmountInformation": { "amount": 199.95, "currency": "CHF" }, "ultimateDebtor": { "addressType": "STRUCTURED", "name": "Pia-Maria Rutschmann-Schnyder", "streetName": "Grosse Marktgasse", "houseNumber": "28", "postalCode": "9400", "city": "Rorschach", "addressLine1": "Rue du Lac 1268/3/1", "addressLine2": "2501 Biel", "country": "CH" }, "paymentReference": { "referenceType": "SCOR", "reference": "RF18539007547034", "additionalInformation": { … } }, "alternativeSchemes": { "alternativeSchemeParameters": [ … ], "alternativeSchemeParameterObjects": [ … ] } }