Create SwissQR Bill API

What this endpoint does

PDF4me Create SwissQR Bill generates Swiss QR payment slips that comply with the Swiss QR-bill standard (Swiss Payment Standards, SPS) through a single REST call. Send creditor and ultimate debtor details, IBAN, amount, currency, reference type, language, separator style, and output format. Optionally include a source document as Base64, blob id, or URL to overlay the slip on an existing PDF. The API returns PDF, PNG, JPEG, or TIFF depending on formatType.

Related Blog Posts

No blog post yet for this feature — coming soon.

In the meantime, browse the PDF4me blog for tutorials and workflows across every platform.

Visit the blog →

Authenticating Your API Request

Every PDF4me REST API call must include your API key in the Authorization header. Create or select a key from the developer dashboard and keep it secret.

Get your API Key

Endpoint

POST/api/v2/CreateSwissQrBill

Postman URLhttps://api.pdf4me.com/api/v2/CreateSwissQrBill

Important Facts You Should Not Miss

Swiss IBAN format is strictly validated

The creditor iban must start with CH followed by 19 digits. An invalid IBAN returns an error.

Use Structured address type (S) for production

Set crAddressType and udAddressType to S so street, house number, postal code, and city are stored separately. This layout is required for most automated Swiss bank reconciliation. Use K (Combined) only when you cannot split address components.

Match referenceType to your reconciliation workflow

NON for payments without a structured reference. QRR for a 27-digit numeric reference on domestic Swiss bills. SCOR for ISO 11649 creditor references. Include reference in the body when using QRR or SCOR.

REST API endpoint

Method: POST
URL: https://api.pdf4me.com/api/v2/CreateSwissQrBill

Set IsAsync to true (PascalCase) for 202 Accepted and poll the Location URL with GET until you receive 200 and the file in JSON. Use false for a synchronous 200 response.

Postman request setup

Setting	Value
Method	POST
URL	https://api.pdf4me.com/api/v2/CreateSwissQrBill
Headers	Content-Type: application/json
Authorization	Basic Auth with your API key, or header Authorization: Basic YOUR_API_KEY
Async	If the response is 202, poll the URL in the Location header (GET) until you get 200 and the file bytes (or JSON with document fields, depending on API version).

Parameters

Always required: iban, crName, crAddressType, crStreetOrAddressLine1, crStreetOrAddressLine2, crPostalCode, crCity, amount, currency, udName, udAddressType, udStreetOrAddressLine1, udStreetOrAddressLine2, udPostalCode, udCity, referenceType, languageType, seperatorLine, formatType, and IsAsync.

Conditional: docContent and docName when overlaying on a PDF; reference when referenceType is QRR or SCOR; pagingOptions and pageNumber when formatType is pdf.

Optional: unstructuredMessage, billingInfo, av1, av2, profiles.

Parameter	Required	Applies when	What it does	Example
docContent	Conditional	Overlay on existing PDF	Omit or empty string = standalone QR slip only. Otherwise Base64 PDF/image bytes (no data: prefix), blob id from POST /api/v2/UploadBlob, or HTTPS URL to the source file.	""
docName	Conditional	With docContent	File name for input/output context. Omit or empty when no source document.	invoice.pdf
iban	Yes	Every request	Creditor Swiss IBAN.	CH0200700110003765824
crName	Yes	Every request	Creditor name or company as registered with the bank.	Test AG
crAddressType	Yes	Every request	S = structured (street + building) or K = combined address lines.	S
crStreetOrAddressLine1	Yes	Every request	If S: street name (max ~70 chars). If K: first address line.	Test Strasse
crStreetOrAddressLine2	Yes	Every request	If S: house number (max ~16). If K: second address line.	1
crPostalCode	Yes	Every request	Creditor postal code (max ~16).	8000
crCity	Yes	Every request	Creditor city (max ~35).	Zurich
amount	Yes	Every request	Payment amount without leading zeros (string). Example: "1000" = 1000.00.	1000
currency	Yes	Every request	CHF or EUR.	CHF
udName	Yes	Every request	Ultimate debtor name or company (required by API; may be empty strings if unused).	Test Debt AG
udAddressType	Yes	Every request	S or K; same rules as crAddressType.	S
udStreetOrAddressLine1	Yes	Every request	Debtor street or address line 1.	Test Deb Strasse
udStreetOrAddressLine2	Yes	Every request	Debtor street number or address line 2.	2
udPostalCode	Yes	Every request	Debtor postal code.	8000
udCity	Yes	Every request	Debtor city.	Zurich
referenceType	Yes	Every request	NON = no reference, QRR = QR reference, SCOR = creditor reference.	NON
reference	Conditional	referenceType = QRR or SCOR	Required for QRR or SCOR; max 27 characters. Omit for NON.	21000000000313947143000017
languageType	Yes	Every request	English, German, French, or Italian.	English
seperatorLine	Yes	Every request	API spelling is seperatorLine (one a). LineWithScissor, DottedLine, or SolidLine.	LineWithScissor
formatType	Yes	Every request	Output format: pdf, png, jpeg, tiff, or null (default PDF behavior).	pdf
pagingOptions	Conditional	formatType = pdf	first, last, AddPageAtEnd, or custom. Omit or null for non-PDF formats.	first
pageNumber	Conditional	pagingOptions = custom	Integer >= 1; single page index when pagingOptions is custom.	1
unstructuredMessage	No	Optional	Free-form payment note. Max 140 characters.	Thank you for your business
billingInfo	No	Optional	Customer billing information.	Invoice for services rendered
av1	No	Optional	Alternative scheme parameter 1.
av2	No	Optional	Alternative scheme parameter 2.
profiles	No	Optional	Custom API profile JSON string. See API documentation for profile options.	{ "someOption": true }
IsAsync	Yes	Every request	PascalCase IsAsync. true = HTTP 202 and poll Location. false = synchronous HTTP 200.	true

Address type options

Applies to crAddressType and udAddressType.

S (Structured)Recommended for automated reconciliation

Stores street, house number, postal code, and city in separate fields. Required by most Swiss banking systems for automated reconciliation.

K (Combined)Two free-form address lines

Stores the address as two combined free-form lines. Simpler to populate but less compatible with automated reconciliation.

Separator line options (seperatorLine)

LineWithScissor

Perforated cutting line with scissors symbols. Default for printed Swiss invoices.

DottedLine

Dotted separator line between invoice and tear-off slip.

SolidLine

Solid separator line without scissors symbols.

Reference type options

NONNo structured reference

Default for simple payments. Use unstructuredMessage for a free-form note instead of reference.

QRR27-digit QR reference

Domestic Swiss bills with PostFinance or Swiss bank IBANs. You must send reference as a 27-digit numeric string.

SCORISO 11649 creditor reference

Cross-border SEPA-style matching. Send reference in ISO 11649 format (starts with RF).

Output format (formatType) and PDF paging

When formatType is pdf, set pagingOptions to control where the QR slip is placed. For image output, omit pagingOptions or set it to null.

formatType: pdfpagingOptions: first

Place QR slip on the first page.

formatType: pdfpagingOptions: last

Place QR slip on the last page.

formatType: pdfpagingOptions: AddPageAtEnd

Append a new page with the QR slip at the end.

formatType: pdfpagingOptions: custom + pageNumber

Place on a specific page (e.g. pageNumber: 1).

formatType: png | jpeg | tiffpagingOptions: null

No paging; returns image bytes.

Output fields

Field	Type	What it contains
docName	String	Output file name.
docContent	Base64	Generated file (PDF or image per formatType). Decode before saving or streaming.

Request examples

Example A: Standalone QR bill (no input PDF)

Omit docContent or send an empty string to generate only the QR payment slip.

{
  "docContent": "",
  "docName": "",
  "iban": "CH0200700110003765824",
  "crName": "Test AG",
  "crAddressType": "S",
  "crStreetOrAddressLine1": "Test Strasse",
  "crStreetOrAddressLine2": "1",
  "crPostalCode": "8000",
  "crCity": "Zurich",
  "amount": "1000",
  "currency": "CHF",
  "udName": "Test Debt AG",
  "udAddressType": "S",
  "udStreetOrAddressLine1": "Test Deb Strasse",
  "udStreetOrAddressLine2": "2",
  "udPostalCode": "8000",
  "udCity": "Zurich",
  "referenceType": "NON",
  "languageType": "English",
  "seperatorLine": "LineWithScissor",
  "formatType": "pdf",
  "pagingOptions": "first",
  "IsAsync": true
}

Example B: Overlay QR on an existing PDF (Base64)

Replace docContent with your PDF as Base64 (no data: prefix).

{
  "docContent": "JVBERi0xLjQKJeLjz9MKMy...",
  "docName": "invoice.pdf",
  "iban": "CH0200700110003765824",
  "crName": "Test AG",
  "crAddressType": "S",
  "crStreetOrAddressLine1": "Test Strasse",
  "crStreetOrAddressLine2": "1",
  "crPostalCode": "8000",
  "crCity": "Zurich",
  "amount": "1000",
  "currency": "CHF",
  "udName": "Test Debt AG",
  "udAddressType": "S",
  "udStreetOrAddressLine1": "Test Deb Strasse",
  "udStreetOrAddressLine2": "2",
  "udPostalCode": "8000",
  "udCity": "Zurich",
  "referenceType": "NON",
  "languageType": "English",
  "seperatorLine": "LineWithScissor",
  "formatType": "pdf",
  "pagingOptions": "custom",
  "pageNumber": 1,
  "IsAsync": true
}

Example C: Copy-paste valid JSON

{
  "docContent": "",
  "docName": "",
  "iban": "CH0200700110003765824",
  "crName": "Test AG",
  "crAddressType": "S",
  "crStreetOrAddressLine1": "Test Strasse",
  "crStreetOrAddressLine2": "1",
  "crPostalCode": "8000",
  "crCity": "Zurich",
  "amount": "1000",
  "currency": "CHF",
  "udName": "Test Debt AG",
  "udAddressType": "S",
  "udStreetOrAddressLine1": "Test Deb Strasse",
  "udStreetOrAddressLine2": "2",
  "udPostalCode": "8000",
  "udCity": "Zurich",
  "referenceType": "NON",
  "languageType": "English",
  "seperatorLine": "LineWithScissor",
  "formatType": "pdf",
  "pagingOptions": "first",
  "IsAsync": true
}

Reference type payloads

No reference (NON):

{ "referenceType": "NON" }

QR reference (QRR):

{
  "referenceType": "QRR",
  "reference": "21000000000313947143000017"
}

Creditor reference (SCOR, ISO 11649):

{
  "referenceType": "SCOR",
  "reference": "RF18539007547034"
}

formatType and pagingOptions snippets

{ "formatType": "png", "pagingOptions": null }

{ "formatType": "pdf", "pagingOptions": "last" }

{ "formatType": "pdf", "pagingOptions": "AddPageAtEnd" }

{ "formatType": "pdf", "pagingOptions": "custom", "pageNumber": 1 }

Code samples

C# Sample

Java Sample

JavaScript Sample

Python Sample

n8n Sample

All API Samples

Integration examples

Common REST integration patternsTypical ways developers call Create SwissQR Bill.

ERP invoice export → Swiss QR bill PDF

1. Your ERP exports invoice data and a PDF.
2. Base64-encode the PDF into docContent.
3. POST payment fields with referenceType QRR and a 27-digit reference.
4. Decode docContent from the response and store or email the QR bill PDF.

Standalone slip or webhook overlay

1. For a tear-off slip only, POST with empty docContent and formatType pdf or png.
2. For invoices from a webhook, Base64-encode the PDF into docContent, set pagingOptions to last or custom, and POST payment fields.
3. Decode the response docContent and upload to object storage or attach to an email API.

Frequently Asked Questions

Which currencies does the API accept?+

Set currency to CHF for domestic Swiss payments or EUR for cross-border transactions. The amount and currency must match what you print on the slip.

What is the difference between NON, QRR, and SCOR?+

They are values for the referenceType field. NON means no structured reference is encoded in the QR code; you can still add unstructuredMessage such as an invoice number. QRR is for domestic Swiss QR-bills: send reference as a 27-digit numeric string when referenceType is QRR. SCOR follows ISO 11649 (starts with RF); send reference when referenceType is SCOR.

Should I use Structured (S) or Combined (K) addresses?+

Use S (Structured) for almost all production integrations. Set crAddressType to S, put the street in crStreetOrAddressLine1, the house number in crStreetOrAddressLine2, and fill crPostalCode and crCity. Use the same pattern for the ultimate debtor with udAddressType and udStreetOrAddressLine fields. Use K (Combined) only when you cannot split the address into separate fields.

Is docContent required?+

No. Omit docContent or send an empty string to generate a standalone QR payment slip. To embed the slip on an invoice, send docContent as Base64 PDF bytes, a blob id from UploadBlob, or a direct HTTPS URL, and set docName when needed for context.

What do formatType and pagingOptions control?+

formatType sets the output: pdf, png, jpeg, or tiff. When formatType is pdf, pagingOptions chooses where the slip is placed: first page, last page, AddPageAtEnd, or custom with pageNumber. For image formats, omit pagingOptions or set it to null.

What does IsAsync do?+

IsAsync controls how the response is delivered. When IsAsync is false (or omitted in samples that use synchronous mode), a successful call returns HTTP 200 with docName and docContent in one JSON body. When IsAsync is true, the API returns HTTP 202 Accepted and a Location header with a poll URL. Send GET requests to that URL until you receive 200 with the same docName and docContent fields. Use async for large batches or slow networks; use sync for simple request-response scripts.

How do I test the API without writing code?+

Open the Create SwissQR Bill API Tester, paste your API key, then fill payment, creditor, and debtor fields, referenceType, languageType, seperatorLine, and IsAsync. Add docContent only when overlaying on a PDF. Use the parameter table on this page as a checklist.

Is the response binary or Base64?+

The response is always JSON, never a raw application/pdf stream. On success the body contains docName (output filename) and docContent (the full PDF encoded as a Base64 string). Decode docContent in your language (for example Buffer.from in Node.js, base64.b64decode in Python, Convert.FromBase64String in C#) before writing the file. Invalid IBAN, missing required fields, or malformed Base64 in docContent typically produce HTTP 400 with an error message in JSON.

What IBAN format is required?+

The iban field must be a valid Swiss creditor IBAN: CH followed by 19 digits (21 characters total), linked to a PostFinance or Swiss bank account. Invalid IBANs cause the request to fail.

Related actions

Create Swiss QR Bill (n8n)

Same backend with workflow UI: Binary Data, URL, standalone slips, format types, and paging options.

Read SwissQR Code

Extract payment data from PDFs that already contain a Swiss QR-bill.

API Tester

Try the endpoint interactively with your API key and sample PDF.

Same task on other platforms

Create Swiss QR Bill (Make)

Visual scenarios with the same SPS-compliant fields and IBAN validation.

Create Swiss QR Bill (Zapier)

Trigger Swiss QR invoicing from SaaS apps and webhooks.

Create Swiss QR Bill (Power Automate)

Microsoft 365 flows with SharePoint, Outlook, and Dynamics integrations.

Create Swiss QR Bill (n8n)

Build self-hosted or cloud n8n workflows with the same Swiss QR-bill fields and output options.

Get Help

Get Your API KeyAPI SamplesAPI TesterGetting Started