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.

Buat Tagihan 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.

Fungsi dari endpoint ini

PDF4me Buat Tagihan SwissQR menghasilkan Swiss QR slip pembayaran yang sesuai dengan peraturan Swiss QR-standar tagihan (Standar Pembayaran Swiss, SPS) melalui satu REST Telepon. Kirim rincian kreditur dan debitur akhir, IBAN, jumlah, mata uang, jenis referensi, bahasa, gaya pemisah, dan format keluaran.Secara opsional, sertakan dokumen sumber sebagai Base64, ID blob, atau URL untuk menempatkan selip di atas yang sudah ada. PDF. Itu API pengembalian PDF, PNG, JPEG, atau TIFF tergantung pada formatType.

Postingan Blog Terkait

Belum ada postingan blog untuk fitur ini — akan segera hadir.

Sementara itu, jelajahi blog PDF4me untuk menemukan tutorial dan alur kerja di berbagai platform.

Kunjungi blog ini →

Memverifikasi Identitas Anda API Meminta

Setiap PDF4me REST API panggilan harus menyertakan Anda API kunci di Authorization Header. Buat atau pilih kunci dari dasbor pengembang dan rahasiakan.

Get your API Key

Titik akhir

POS/api/v2/CreateSwissQrBill

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

Fakta Penting yang Tidak Boleh Anda Lewatkan

Format IBAN Swiss divalidasi secara ketat.

Kreditur mereka akan pergi harus dimulai dengan CH diikuti oleh 19 digit. Tidak valid IBAN Mengembalikan kesalahan.

Gunakan tipe alamat terstruktur (S) untuk produksi

Mengatur crAddressType Dan udAddressType ke S Jadi, jalan, nomor rumah, kode pos, dan kota disimpan secara terpisah. Tata letak ini diperlukan untuk sebagian besar rekonsiliasi bank Swiss otomatis. Gunakan K (Gabungan) hanya jika Anda tidak dapat memisahkan komponen alamat.

Cocokkan referenceType dengan alur kerja rekonsiliasi Anda.

NON untuk pembayaran tanpa referensi terstruktur. QRR untuk referensi numerik 27 digit pada uang kertas domestik Swiss. SKOR untuk ISO 11649 Referensi kreditur. Sertakan referensi di dalam tubuh saat digunakan QRR atau SCOR.

REST API titik akhir

Metode: POS
URL: https://api.pdf4me.com/api/v2/CreateSwissQrBill

Mengatur IsAsync ke BENAR (PascalCase) untuk 202 Accepted dan jajak pendapat Lokasi URL dengan GET sampai Anda menerima 200 dan berkas di JSON. Menggunakan PALSU untuk sinkron 200 tanggapan.

Pengaturan permintaan Postman

Pengaturan	Nilai
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).

Parameter

Selalu diperlukan: mereka akan pergi, crName, crAddressType, crJalanAtauAlamatBaris1, crJalanAtauAlamatBaris2, Kode Pos cr, Kota cr, jumlah, mata uang, udName, udAddressType, udStreetOrAddressLine1, udStreetOrAddressLine2, Kode Pos ud, Kota ud, tipe referensi, Jenis bahasa, garis pemisah, formatType, Dan IsAsync.

Bersyarat: Konten dokumen Dan Nama dokumen saat ditambahkan di atas PDF; referensi Kapan tipe referensi adalah QRR atau SKOR; Opsi penomoran halaman Dan Nomor halaman Kapan formatType adalah PDF.

Opsional: pesan tidak terstruktur, Informasi penagihan, av1, av2, profil.

Parameter	Diperlukan	Berlaku saat	Apa fungsinya?	Contoh
`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`

Opsi jenis alamat

Berlaku untuk crAddressType Dan udAddressType.

S (Terstruktur)Direkomendasikan untuk rekonsiliasi otomatis

Menyimpan alamat jalan, nomor rumah, kode pos, dan kota dalam kolom terpisah. Diperlukan oleh sebagian besar sistem perbankan Swiss untuk rekonsiliasi otomatis.

K (Gabungan)Dua baris alamat bebas bentuk

Menyimpan alamat sebagai dua baris bebas yang digabungkan. Lebih mudah diisi tetapi kurang kompatibel dengan rekonsiliasi otomatis.

Opsi garis pemisah (`seperatorLine`)

GarisDenganGunting

Garis potong berlubang dengan simbol gunting. Standar untuk faktur Swiss yang dicetak.

Garis Putus-putus

Garis pemisah putus-putus antara faktur dan slip yang dapat disobek.

Garis Padat

Garis pemisah solid tanpa simbol gunting.

Opsi tipe referensi

NONTidak ada referensi terstruktur

Pengaturan default untuk pembayaran sederhana. Gunakan pesan tidak terstruktur untuk catatan bentuk bebas sebagai gantinya referensi.

QRRReferensi QR 27 digit

Uang kertas domestik Swiss dengan PostFinance atau bank Swiss IBANsAnda harus mengirim referensi sebagai string numerik 27 digit.

SKORReferensi kreditor ISO 11649

Lintas batas SEPAPencocokan gaya. Kirim referensi di dalam ISO 11649 format (dimulai dengan RF).

Format keluaran (`formatType`) Dan PDF panggilan

Kapan formatType adalah PDF, mengatur Opsi penomoran halaman untuk mengontrol di mana QR slip ditempatkan. Untuk keluaran gambar, hilangkan Opsi penomoran halaman atau atur ke batal.

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.

Bidang keluaran

Bidang	Jenis	Isi di dalamnya
`docName`	String	Output file name.
`docContent`	Base64	Generated file (PDF or image per formatType). Decode before saving or streaming.

Minta contoh

Contoh A: Mandiri QR tagihan (tanpa masukan) PDF)

Hilangkan Konten dokumen atau kirim string kosong untuk hanya menghasilkan QR slip pembayaran.

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

Contoh B: Hamparan QR pada yang sudah ada PDF (Base64)

Mengganti Konten dokumen dengan milikmu PDF sebagai Base64 (TIDAK data: awalan).

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

Contoh C: Salin-tempel 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
}

Muatan tipe referensi

Tidak ada referensi (NON):

{ "referenceType": "NON" }

Referensi QR (QRR):

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

Referensi kreditur (SCOR, ISO 11649):

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

Cuplikan formatType dan pagingOptions

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

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

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

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

Contoh kode

Contoh integrasi

Pola integrasi REST umumTypical ways developers call Create SwissQR Bill.

Ekspor faktur ERP → PDF faktur QR Swiss

Sistem ERP Anda mengekspor data faktur dan file PDF.
Encode PDF ke dalam Base64 Konten dokumen.
Kolom pembayaran POST dengan tipe referensi QRR dan 27 digit referensi.
Dekode Konten dokumen dari respons tersebut dan simpan atau kirim email PDF tagihan QR.

Lapisan slip atau webhook mandiri

Untuk slip yang bisa disobek saja, POST dengan kosong Konten dokumen Dan formatType pdf atau png.
Untuk faktur dari webhook, encode PDF ke dalam format Base64. Konten dokumen, mengatur Opsi penomoran halaman ke terakhir atau kebiasaan, dan kolom pembayaran POST.
Uraikan responsnya Konten dokumen dan mengunggah ke penyimpanan objek atau melampirkannya ke API email.

Pertanyaan yang Sering Diajukan

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.