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.ch

API 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 Key
582c9ea9-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

Download OpenAPI description
api-docs.json
api-docs.yaml
Overview
URL

https://www.qr-invoice.ch

Codeblock GmbH

contact@codeblock.ch

License

Commercial license

Languages
Servers
Generated server url

https://rest.qr-invoice.cloud/

00 Example Data

Various example data that can be used as example input to other services

Operations

QR Reference

Request

Security
X-API-Key or api_key
curl -i -X GET \
  https://rest.qr-invoice.cloud/v2/examples/qr-reference \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

QR Reference

Bodytext/plain
string

QrInvoice - Example without Reference Number

Request

Security
X-API-Key or api_key
curl -i -X GET \
  https://rest.qr-invoice.cloud/v2/examples/qr-invoice/without-reference \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

QrInvoice

Bodyapplication/json
creditorInformationobject(CreditorInformation)required
creditorInformation.​ibanstring= 21 charactersrequired

IBAN or QR-IBAN of the creditor.
Fixed length: 21 alphanumeric characters, only IBANs with CH or LI country code permitted.

Example: "CH3908704016075473007"
creditorInformation.​creditorobject(Creditor)required
creditorInformation.​creditor.​addressTypestring= 1 charactersrequired

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

Enum"STRUCTURED""COMBINED"
Example: "STRUCTURED"
creditorInformation.​creditor.​namestring[ 1 .. 70 ] charactersrequired

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

Example: "Robert Schneider AG"
creditorInformation.​creditor.​streetNamestring[ 1 .. 70 ] characters

Street/P.O. box of the creditor
Maximum 70 characters permitted, may not include any house or building number.

Example: "Rue du Lac"
creditorInformation.​creditor.​houseNumberstring[ 1 .. 16 ] characters

House number of the creditor
Maximum 16 characters permitted

Example: "1268/2/22"
creditorInformation.​creditor.​postalCodestring[ 1 .. 16 ] charactersrequired

Postal code of the creditor
Maximum 16 characters permitted. The postal code is always to be entered without a country code prefix.

Example: "2501"
creditorInformation.​creditor.​citystring[ 1 .. 35 ] charactersrequired

City of the creditor
Maximum 35 characters permitted

Example: "Biel"
creditorInformation.​creditor.​countrystring= 2 charactersrequired

Country of the creditor
Two-digit country code according to ISO 3166-1

Example: "CH"
creditorInformation.​creditor.​addressLine1string[ 1 .. 70 ] charactersDeprecated

Address line 1 including street and building number or P.O. Box
Maximum 70 characters permitted

Example: "Rue du Lac 1268/2/22"
creditorInformation.​creditor.​addressLine2string[ 1 .. 70 ] charactersDeprecated

Address line 2 including postal code and town from creditor’s address
Maximum 70 characters permitted
Must be provided for address type "K".

Example: "2501 Biel"
ultimateCreditorobject(UltimateCreditor)
paymentAmountInformationobject(PaymentAmountInformation)required
paymentAmountInformation.​amountnumber[ 0 .. 999999999 ]

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.

Example: 199.95
paymentAmountInformation.​currencystring= 3 charactersrequired

The payment currency, 3-digit alphanumeric currency code according to ISO 4217
Only CHF and EUR are permitted.

Enum"EUR""CHF"
Example: "CHF"
ultimateDebtorobject(UltimateDebtor)
paymentReferenceobject(PaymentReference)required
paymentReference.​referenceTypestring[ 3 .. 4 ] charactersrequired

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

Enum"QRR""SCOR""NON"
Example: "SCOR"
paymentReference.​referencestring[ 0 .. 27 ] characters

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

Example: "RF18539007547034"
paymentReference.​additionalInformationobject(AdditionalInformation)
alternativeSchemesobject(AlternativeSchemes)
Response
application/json
{
  "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": [ … ]
  }
}

QrInvoice - Example without Amount

Request

Security
X-API-Key or api_key
curl -i -X GET \
  https://rest.qr-invoice.cloud/v2/examples/qr-invoice/without-amount \
  -H 'X-API-Key: YOUR_API_KEY_HERE'

Responses

QrInvoice

Bodyapplication/json
creditorInformationobject(CreditorInformation)required
creditorInformation.​ibanstring= 21 charactersrequired

IBAN or QR-IBAN of the creditor.
Fixed length: 21 alphanumeric characters, only IBANs with CH or LI country code permitted.

Example: "CH3908704016075473007"
creditorInformation.​creditorobject(Creditor)required
creditorInformation.​creditor.​addressTypestring= 1 charactersrequired

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

Enum"STRUCTURED""COMBINED"
Example: "STRUCTURED"
creditorInformation.​creditor.​namestring[ 1 .. 70 ] charactersrequired

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

Example: "Robert Schneider AG"
creditorInformation.​creditor.​streetNamestring[ 1 .. 70 ] characters

Street/P.O. box of the creditor
Maximum 70 characters permitted, may not include any house or building number.

Example: "Rue du Lac"
creditorInformation.​creditor.​houseNumberstring[ 1 .. 16 ] characters

House number of the creditor
Maximum 16 characters permitted

Example: "1268/2/22"
creditorInformation.​creditor.​postalCodestring[ 1 .. 16 ] charactersrequired

Postal code of the creditor
Maximum 16 characters permitted. The postal code is always to be entered without a country code prefix.

Example: "2501"
creditorInformation.​creditor.​citystring[ 1 .. 35 ] charactersrequired

City of the creditor
Maximum 35 characters permitted

Example: "Biel"
creditorInformation.​creditor.​countrystring= 2 charactersrequired

Country of the creditor
Two-digit country code according to ISO 3166-1

Example: "CH"
creditorInformation.​creditor.​addressLine1string[ 1 .. 70 ] charactersDeprecated

Address line 1 including street and building number or P.O. Box
Maximum 70 characters permitted

Example: "Rue du Lac 1268/2/22"
creditorInformation.​creditor.​addressLine2string[ 1 .. 70 ] charactersDeprecated

Address line 2 including postal code and town from creditor’s address
Maximum 70 characters permitted
Must be provided for address type "K".

Example: "2501 Biel"
ultimateCreditorobject(UltimateCreditor)
paymentAmountInformationobject(PaymentAmountInformation)required
paymentAmountInformation.​amountnumber[ 0 .. 999999999 ]

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.

Example: 199.95
paymentAmountInformation.​currencystring= 3 charactersrequired

The payment currency, 3-digit alphanumeric currency code according to ISO 4217
Only CHF and EUR are permitted.

Enum"EUR""CHF"
Example: "CHF"
ultimateDebtorobject(UltimateDebtor)
paymentReferenceobject(PaymentReference)required
paymentReference.​referenceTypestring[ 3 .. 4 ] charactersrequired

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

Enum"QRR""SCOR""NON"
Example: "SCOR"
paymentReference.​referencestring[ 0 .. 27 ] characters

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

Example: "RF18539007547034"
paymentReference.​additionalInformationobject(AdditionalInformation)
alternativeSchemesobject(AlternativeSchemes)
Response
application/json
{
  "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": [ … ]
  }
}

10 QR Invoice Documents including Payment Part & Receipt (QR Bill)

Operations

11 Payment Part & Receipt (QR Bill)

Operations

12 Swiss QR Code

Operations

13 Swiss Payments Code

Operations

20 IBAN

Operations

21 QR Reference (QRR)

Operations

22 Creditor Reference (SCOR)

Operations

23 Country Codes

According to ISO 3166-1 alpha-2

Operations

30 Bill Information

Operations

31 Alternative Schemes

Operations

90 PDF

Operations

99 Authentication

Operations

XX Deprecated QR Invoice Operations v1

Version 1 of QR Invoice REST API

Operations