Swiss QR Invoice

The QR invoice, or QR bill, is utilized to initiate payment transactions in Switzerland and is considered equivalent to the EPC QR code of the European Union. In addition to the QR code, the QR-bill includes a section that displays the information in human-readable form.

An example QR invoice (with size set to QR_BILL) with which 150 CHF will be donated to the Swiss Red Cross:

An example of a swiss QR bill that donates 150 CHF to the Swiss Red Cross

Endpoints

The API is available as a POST request. By specifying the Accept header, the desired format of the response can be specified. The following formats are currently supported:

  • PDF (application/pdf)
  • SVG (image/svg+xml, application/svg+xml)
  • PNG (image/png)

POST/v1/swiss-qr-invoice 

curl -X POST https://api.apistax.io/v1/swiss-qr-invoice \
    -o 'qr-code.png' \
    -H 'Authorization: Bearer API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -H 'Accept: image/png' \
    -d '{
          "creditor": {
            "iban": "CH00 0000 0000 0000 0000",
            "name": "Max Mustermann",
            "postalCode": "3000",
            "city": "Bern"
          }
        }'

Parameters

creditor: Object

Creditor information. At least iban, name, postalCode and city must be specified.

iban: String

The international bank account number of the creditor. All spaces between the blocks are removed. The IBAN must originate from Switzerland or Lichtenstein and thus must begin with CH or LI.

name: String

The creditors name. The name must not exceed 70 characters in length.

street: String

The creditors street name. The street must not exceed 70 characters in length.

postalCode: String

The creditors postal code. The code must not exceed 16 characters in length.

city: String

The creditors city name. The city must not exceed 35 characters in length.

country: String = CH

The creditors country code as ISO 3166-1 alpha-2 code. Defaults to CH.

debtor: Object

Debtor information. This object is optional, but if it is provided, at least name, postalCode and city must be specified.

name: String

The debtors name. The name must not exceed 70 characters in length.

street: String

The debtors street name. The street must not exceed 70 characters in length.

postalCode: String

The debtors postal code. The code must not exceed 16 characters in length.

city: String

The debtors city name. The city must not exceed 35 characters in length.

country: String = CH

The debtors country code as ISO 3166-1 alpha-2 code. Defaults to CH.

currency: String = CHF

The currency according to ISO 4217. Only CHF or EUR is allowed. Defaults to CHF.

amount: Float

The payment amount should be specified with a maximum of two decimal places. The value is optional, but recommended.

information: String

Unstructured information which can be used for example for payment purpose. The information must not exceed 140 characters in length.

structuredInformation: String

Structured information contains coded information for automated booking of the payment. The syntax definition in the latest version can be found at swico.ch.

reference: String

The reference is either a QR reference (if a QR-IBAN is used in creditor.iban) or an ISO 11649 creditor reference.

size: String = QR_CODE

The requested output format can be either a QR_CODE, QR_BILL or A4_SHEET. Additional information about the output size and format can be found in the output formats section.

language: String = EN

The language in which the documents should be created. Only used if QR_BILL or A4_SHEET is passed for size. Available values are DE, FR, IT and EN. Defaults to EN.

If all parameters are utilized, a hypothetical curl request could look like this:

curl -X POST https://api.apistax.io/v1/swiss-qr-invoice \
    -o 'a4-sheet.png' \
    -H 'Authorization: Bearer API_KEY_HERE' \
    -H 'Content-Type: application/json' \
    -H 'Accept: image/png' \
    -d '{
          "creditor": {
            "iban": "CH07 3000 0017 3000 9700 0",
            "name": "Schweizerisches Rotes Kreuz",
            "street": "Postfach",
            "postalCode": "3001",
            "city": "Bern",
            "country": "CH"
          },
          "debtor": {
            "name": "Max Mustermann",
            "street": "Musterstraße 1",
            "postalCode": "3000",
            "city": "Bern",
            "country": "CH"
          },
          "currency": "CHF",
          "amount": 150.00,
          "information": "Emergency relief",
          "reference": "00 00000 00371 40000 00000 85842",
          "size": "A4_SHEET",
          "language": "EN"
        }'

Output formats

The API supports multiple output formats. These formats could be controlled by the size parameter.

Possible output formats of QR invoice

A4 Sheet (A4_SHEET)
Creates a A4 portrait page (210 x 297 mm) with the QR bill at the bottom.

QR Bill (QR_BILL)
Creates a QR bill payment slip (210 x 110 mm).

QR Code (QR_CODE)
Creates the QR code only (46 x 46mm).

Possible errors

Identifier Description
message.countryMustBeValid Parameter country must be valid and provided as an ISO 3166-1 alpha-2 code.
message.currencyMustBeValid Parameter currency must be valid and provided as an ISO 4217 currency code.
message.ibanMustBeValid Parameter iban must be valid.
message.ibanMustNotBeBlank Parameter iban is required.
message.ibanMustContainValidCountryCode Parameter iban must be valid and must begin with CH or LI.
message.creditorMustNotBeNull Parameter creditor is required.
message.nameMustNotBeBlank Parameter name is required.
message.postalCodeMustNotBeBlank Parameter postalCode is required.
message.cityMustNotBeBlank Parameter city is required.
message.informationMustNotBeLongerThan140Characters Parameter information must be maximum 140 characters long.
message.structuredInformationMustBeValid Parameter structuredInformation must be a valid swico.ch information.
message.structuredInformationMustBeLongerThan3Characters Parameter structuredInformationmust be minimum 3 characters long.
message.structuredInformationMustNotBeLongerThan140Characters Parameter structuredInformationmust be maximum 140 characters long.
message.nameMustNotBeLongerThan70Characters Parameter name must be maximum 70 characters long.
message.streetMustNotBeLongerThan70Characters Parameter street must be maximum 70 characters long.
message.postalCodeMustNotBeLongerThan16Characters Parameter postalCode must be maximum 16 characters long.
message.cityMustNotBeLongerThan35Characters Parameter city must be maximum 35 characters long.
message.amountMustNotBeSmallerThan1 Parameter amount must be between 1 and 99999999999.
message.amountMustNotBeBiggerThan99999999999 Parameter amount must be between 1 and 99999999999.
message.referenceMustBeValid Parameter reference must be valid and provided as ISO 11649 or QR reference.
message.qrIbanRequiresValidQrReference If a QR IBAN is used, a valid QR reference must be specified.
message.qrReferenceRequiresQrIban If a QR reference is used, a QR IBAN must be specified.

It should be noted that there are a number of common error messages, which can be found in the "Possible errors" section of the general documentation.

Swiss QR Invoice costs
Generate Swiss QR bills to use it on your invoice documents.
1
Credits spent
Credit cost per REST call
0,0040
EUR per call
Price depends on your subscription