Which currencies does Create SwissQR Bill accept?

Use CHF for domestic Swiss invoicing and EUR for cross-border payments. Set the currency field to match the invoice and the creditor IBAN.

What is the difference between reference types NON, QRR, and SCOR?

NON omits a structured reference in the QR code. QRR embeds a 27-digit numeric QR reference for domestic Swiss reconciliation with PostFinance or Swiss bank IBANs; you must send a valid reference in the request body. SCOR embeds an ISO 11649 creditor reference (RF prefix) for SEPA-style matching; you must send reference as well. Use unstructuredMessage for a free-form note when referenceType is NON.

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

Use S (Structured) for production. Map street to crStreetOrAddressLine1, house number to crStreetOrAddressLine2, plus crPostalCode and crCity (same pattern for ud fields). K (Combined) uses two free-form lines only. Structured is required for most automated Swiss bank reconciliation.

Is the API response binary or Base64?

The API returns JSON, not raw binary. On success you receive docName and docContent where docContent is the PDF as a Base64 string. Decode before saving. With IsAsync true you first get 202 Accepted and a Location header to poll until the same JSON is returned.

Créer une facture SwissQR API

Q: What IBAN format is required?

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

Que fait ce point de terminaison ?

PDF4me Créer une facture SwissQR génère des Suisses QR bordereaux de paiement conformes à la législation suisse QR-norme de facturation (Normes de paiement suisses, SPS) par l'intermédiaire d'un seul REST appel. Envoyer Informations relatives au créancier et au débiteur final, IBAN, montant, devise, type de référence, langue, style de séparateur et format de sortieIncluez éventuellement un document source comme Base64, identifiant blob, ou URL recouvrir le glissement sur un existant PDF. Le API retours PDF, PNG, JPEG, ou TIFF selon type de format.

Articles de blog connexes

Il n'y a pas encore d'article de blog consacré à cette fonctionnalité — à venir prochainement.

En attendant, n'hésitez pas à consulter le blog de PDF4me pour découvrir des tutoriels et des procédures de travail adaptés à toutes les plateformes.

Consultez le blog →

Authentification de votre API Demande

Chaque PDF4me REST API L'appel doit inclure votre API clé dans le Authorization En-tête. Créez ou sélectionnez une clé depuis le tableau de bord développeur et gardez-la secrète.

Get your API Key

Point de terminaison

POSTE/api/v2/CreateSwissQrBill

URL Postmanhttps://api.pdf4me.com/api/v2/CreateSwissQrBill

Informations importantes à ne pas manquer

Le format IBAN suisse est strictement validé.

Le créancier ils allaient doit commencer par CH suivi de 19 chiffres. Une valeur invalide IBAN renvoie une erreur.

Utilisez le type d'adresse structurée (S) pour la production

Ensemble crAddressType et udAddressType à S Ainsi, la rue, le numéro, le code postal et la ville sont stockés séparément. Cette structure est requise pour la plupart des rapprochements bancaires automatisés en Suisse. K (Combiné) uniquement lorsque vous ne pouvez pas séparer les composants de l'adresse.

Associez le type de référence à votre flux de travail de rapprochement.

NON pour les paiements sans référence structurée. QRR pour une référence numérique à 27 chiffres sur les billets suisses nationaux. SCORE pour ISO 11649 Références de créanciers. Veuillez inclure : référence dans le corps lors de l'utilisation QRR ou SCOR.

REST API point de terminaison

Méthode: POSTE
URL : https://api.pdf4me.com/api/v2/CreateSwissQrBill

Ensemble IsAsync à vrai (PascalCase) pour 202 Accepted et sonder le Emplacement URL avec GET jusqu'à ce que vous receviez 200 et le fichier dans JSON. Utiliser FAUX pour une synchronisation 200 réponse.

Configuration de la requête Postman

Paramètre	Valeur
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).

Paramètres

Toujours requis : ils allaient, crName, crAddressType, crRueOuAdresseLigne1, crRueOuAdresseLigne2, crCodePostal, crCity, montant, devise, udName, udAddressType, udStreetOrAddressLine1, udStreetOrAddressLine2, udCodePostal, udCity, type de référence, type de langue, ligne de séparation, type de format, et IsAsync.

Conditionnel: docContent et Nom du document lors de la superposition sur un PDF ; référence quand type de référence est QRR ou SCORE; options de pagination et numéro de page quand type de format est pdf.

Facultatif: message non structuré, informations de facturation, av1, av2, profils.

Paramètre	Requis	S'applique lorsque	Ce que cela fait	Exemple
`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`

options de type d'adresse

S'applique à crAddressType et udAddressType.

S (Structuré)Recommandé pour la réconciliation automatisée

Enregistre la rue, le numéro, le code postal et la ville dans des champs distincts. Ces informations sont requises par la plupart des systèmes bancaires suisses pour le rapprochement bancaire automatisé.

K (Combiné)Deux lignes d'adresse libres

Enregistre l'adresse sur deux lignes libres combinées. Plus simple à remplir, mais moins compatible avec le rapprochement automatisé.

Options de ligne de séparation (`seperatorLine`)

Ligne avec ciseaux

Ligne de découpe perforée avec symboles de ciseaux. Par défaut pour les factures suisses imprimées.

Ligne pointillée

Ligne de séparation en pointillés entre la facture et le coupon détachable.

Ligne solide

Ligne de séparation continue sans symboles de ciseaux.

options de type de référence

NONAucune référence structurée

Valeur par défaut pour les paiements simples. Utiliser message non structuré pour une note libre au lieu de référence.

QRRRéférence QR à 27 chiffres

Billets suisses nationaux avec PostFinance ou banque suisse IBANsVous devez envoyer référence sous forme de chaîne numérique de 27 chiffres.

SCORERéférence du créancier ISO 11649

Transfrontalière SEPACorrespondance de style. Envoyer référence dans ISO 11649 format (commence par RF).

Format de sortie (`formatType`) et PDF pagination

Quand type de format est pdf, ensemble options de pagination pour contrôler où le QR Le document est inséré. Pour l'affichage de l'image, omettez-le. options de pagination ou le régler sur nul.

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.

Champs de sortie

Champ	Taper	Ce qu'il contient
`docName`	String	Output file name.
`docContent`	Base64	Generated file (PDF or image per formatType). Decode before saving or streaming.

Exemples de demandes

Exemple A : Autonome QR facture (sans entrée) PDF)

Omettre docContent ou envoyez une chaîne vide pour générer uniquement le QR reçu de paiement.

{
  "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
}

Exemple B : Superposition QR sur un existant PDF (Base64)

Remplacer docContent avec votre PDF comme Base64 (Non données: préfixe).

{
  "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
}

Exemple C : Copier-coller valide 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
}

charges utiles de type référence

Aucune référence (NON) :

{ "referenceType": "NON" }

Référence QR (QRR) :

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

Référence du créancier (SCOR, ISO 11649) :

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

extraits de code formatType et pagingOptions

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

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

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

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

Exemples de code

Exemples d'intégration

Modèles d'intégration REST courantsTypical ways developers call Create SwissQR Bill.

Exportation de factures ERP → Facture suisse QR PDF

Votre ERP exporte les données de facturation et un PDF.
Encoder le PDF en Base64 docContent.
Champs de paiement POST avec type de référence QRR et un code à 27 chiffres référence.
Décoder docContent à partir de la réponse, stockez ou envoyez par e-mail le PDF de la facture QR.

Glissière autonome ou superposition de crochet

Pour obtenir uniquement un coupon détachable, envoyez par la poste avec une enveloppe vide. docContent et type de format pdf ou png.
Pour les factures provenant d'un webhook, encodez le PDF en Base64. docContent, ensemble options de pagination à dernier ou coutume, et les champs de paiement POST.
Décodez la réponse docContent et les télécharger sur un système de stockage d'objets ou les joindre à une API de messagerie électronique.

Foire aux 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.