Overview
The ZUGFeRD/Factur‑X integration is an enterprise‑grade, EN 16931–aligned solution for producing compliant e‑invoices embedded in PDF/A‑3. It delivers a transparent, field‑by‑field mapping from Younium data to ZUGFeRD structures with BT/BG schema codes, supports Basic/Comfort/Extended profiles, and provides configurable “Zugferd custom mappings” for business overrides (for example, BuyerReference, BuyerIBAN, and IsCorrectionInvoice). Built on the proven ZUGFeRD library engine, it includes robust VAT handling (including exemption reasons), credit/correction flows with proper referencing, and secure, auditable generation designed for scale and ongoing interoperability improvements.
Field Mapping Overview
Parties (Seller → Buyer)
| Younium Field | ZUGFeRD Field | Notes |
|---|---|---|
Legal Entity Seller name (LegalEntity.Name) | Seller name | zugferd schema code BT‑27 |
Legal Entity Seller street (LegalEntity.Address.Street) | Seller postal address: Address line 1 | zugferd schema code BG‑5/BT‑37 |
Legal Entity Seller city (LegalEntity.Address.City) | Seller postal address: City | zugferd schema code BG‑5/BT‑36 |
Legal Entity Seller postcode (LegalEntity.Address.Zip) | Seller postal address: Post code | zugferd schema code BG‑5/BT‑35 |
Legal Entity Seller country (LegalEntity.Address.Country) | Seller postal address: Country code | zugferd schema code BG‑5/BT‑40 |
Invoice Seller contact (Invoice.OurReference) | Seller contact name | zugferd schema code BG‑6 |
Legal Entity Seller VAT ID (LegalEntity.TaxRegistrationNumber) | Seller VAT identifier | zugferd schema code BT‑31 |
Account Buyer name (Account.Name) | Buyer name | zugferd schema code BT‑44 |
Account Buyer street (Account.InvoiceAddress.Street) | Buyer postal address: Address line 1 | zugferd schema code BG‑8/BT‑50 |
Account Buyer city (Account.InvoiceAddress.City) | Buyer postal address: City | zugferd schema code BG‑8/BT‑53 |
Account Buyer postcode (Account.InvoiceAddress.Zip) | Buyer postal address: Post code | zugferd schema code BG‑8/BT‑52 |
Invoice Buyer country (Invoice.InvoiceAddress.Country) | Buyer postal address: Country code | zugferd schema code BG‑8/BT‑54 |
Invoice Buyer contact (Invoice.YourReference) | Buyer contact name | zugferd schema code BG‑9/BT‑56 |
Account Buyer VAT ID (Account.TaxRegistrationNumber) | Buyer VAT identifier | zugferd schema code BT‑48 |
Invoice Buyer reference (Invoice.ReferenceNumber) OR ZUGFeRD Account custom mapping “BuyerReference” OR ZUGFeRD Invoice custom mapping “BuyerReference” | Buyer reference | zugferd schema code BT‑10. Custom mapping available: Account (“BuyerReference”) and Invoice (“BuyerReference”). |
Document header and references
| Younium Field | ZUGFeRD Field | Notes |
|---|---|---|
Invoice Invoice number (Invoice.InvoiceNumber) | Invoice number | zugferd schema code BT‑1 |
Invoice Invoice date (Invoice.InvoiceDate) | Invoice issue date | zugferd schema code BT‑2 |
Invoice Currency (Invoice.Currency.Code) | Invoice currency code | zugferd schema code BT‑5 |
Invoice Buyer order number (Invoice.YourOrderNumber) | Buyer order reference (Purchase order) | zugferd schema code BT‑13. Same order number is also used for Seller order reference (see next row). |
Invoice Seller order number (Invoice.YourOrderNumber) | Seller order reference (Sales order) | zugferd schema code BT‑14. Same as Buyer order reference by design. |
Invoice Preceding invoice link (credit/correction context) | Preceding invoice reference/date | zugferd schema code BT‑25 / BT‑26. Only populated for Credit Notes and Corrections (based on debit/credit link or cancellation). A note like “Credit for invoice …” or “Cancellation of invoice …” is added. |
Invoice Note (Invoice.Notes) | Document note | Free‑text; outside core BT. |
Payment information (terms, means, accounts)
| Younium Field | ZUGFeRD Field | Notes |
|---|---|---|
Invoice Due date (Invoice.DueDate) | Payment due date | zugferd schema code BT‑9 |
Invoice Payment terms text (“Invoice due date: {Invoice.DueDate}”) | Payment terms (description) | zugferd schema code BT‑20 |
Invoice/Legal Entity Creditor IBAN (Invoice.BankAccount.IBAN OR LegalEntity.IBAN if enabled) | Payment account identifier (IBAN) | zugferd schema code BT‑84 |
Invoice/Legal Entity Creditor BIC (Invoice.BankAccount.BIC OR LegalEntity.BIC if enabled) | Payment service provider identifier (BIC) | zugferd schema code BT‑86 |
Invoice Creditor account name (Invoice.BankAccount.Name) | Payment account name | zugferd schema code BT‑85 |
Account Buyer IBAN (ZUGFeRD Account custom mapping “BuyerIBAN”) OR settings.IbanCustomFieldMappingField | Debited account identifier (Buyer IBAN) | zugferd schema code BT‑91. Prefer ZUGFeRD custom mapping “BuyerIBAN”. Note: settings.IbanCustomFieldMappingField is deprecated and will be removed. |
Derived Presence of Buyer IBAN | Payment means type code | zugferd schema code BT‑81. SEPA Credit Transfer when Buyer IBAN present; Cash otherwise. |
Totals (document)
| Younium Field | ZUGFeRD Field | Notes |
|---|---|---|
Invoice Subtotal amount (Invoice.Subtotal.Amount) | Sum of invoice line net amount | zugferd schema code BT‑106 |
Invoice Subtotal amount (Invoice.Subtotal.Amount) | Tax basis amount | zugferd schema code BT‑110 |
Invoice VAT amount (Invoice.Tax.Amount) | Invoice total VAT amount | zugferd schema code BT‑111 |
Invoice Total amount (Invoice.TotalAmount.Amount) | Invoice total amount with VAT | zugferd schema code BT‑112 |
Invoice Amount due (Invoice.TotalAmount.Amount) | Amount due for payment | zugferd schema code BT‑115 |
VAT breakdown (per VAT rate group)
| Younium Field | ZUGFeRD Field | Notes |
|---|---|---|
Lines Grouped by VAT rate | VAT category taxable amount | zugferd schema code BT‑116 |
Lines Grouped by VAT rate | VAT category tax amount | zugferd schema code BT‑117 |
| Line VAT situation | VAT category code | zugferd schema code BT‑95. VAT>0 → S; VAT=0 with EU reverse‑charge → AE; VAT=0 treated as export/out‑of‑scope → G. When AE or G is used, exemption reason text and code are added. |
| Line VAT rate | VAT rate (%) | zugferd schema code BT‑96 |
| Standard texts/codes for AE/G | VAT exemption reason text/code | zugferd schema code BT‑120 / BT‑121. |
Lines (per invoice line)
| Younium Field | ZUGFeRD Field | Notes |
|---|---|---|
Invoice Line Item name (InvoiceLine.ProductName) | Item name | zugferd schema code BT‑153 |
Invoice Line Description (InvoiceLine.ChargeDescription) | Item description | zugferd schema code BT‑154 |
Invoice Line UoM (InvoiceLine.UnitOfMeasure) | Invoiced quantity unit of measure | zugferd schema code BT‑130. Mapped to UN/ECE (hours→HUR, pieces→H87; default H87). |
Invoice Line Quantity (derived to match totals) | Invoiced quantity | zugferd schema code BT‑129 |
Invoice Line Net unit price (derived) | Price details (net unit) | BG‑29 |
Invoice Line Gross unit price (from amounts) | Price details (gross unit) | BG‑29 |
Invoice Line Net amount (NetUnitPrice × Quantity) | Invoice line net amount | zugferd schema code BT‑131 |
Invoice Line VAT category (from VAT logic) | Item VAT category code | zugferd schema code BT‑151 |
Invoice Line VAT rate | Item VAT rate (%) | zugferd schema code BT‑152 |
Invoice Line Service period or Invoice date | Invoicing period (line) / Delivery date | zugferd schema code BG‑26 |
Corrections and credits
| Younium Field | ZUGFeRD Field | Notes |
|---|---|---|
Invoice Correction flag (ZUGFeRD Invoice custom mapping OR ZugferdSettings Invoice Correction Flag Custom Field Mapping | Invoice type: Correction | zugferd schema code BT‑3. Preceding invoice reference/date set only for Invoice Correction Flag Custom Field Mapping is deprecated. |
Invoice Credit (Invoice.InvoiceType = Credit OR Invoice.TotalAmount.Amount < 0) | Invoice type: Credit Note | zugferd schema code BT‑3. Preceding invoice reference/date set; “Credit for invoice …” note added. |
Customizable overrides (summary)
| Mapping Name | Sources | ZUGFeRD Field | Notes |
|---|---|---|---|
| Buyer reference | Invoice Buyer reference OR ZUGFeRD Account custom mapping OR ZUGFeRD Invoice custom mapping | Buyer reference — BT‑10 | Account and Invoice mappings override defaults when set. |
| Buyer IBAN | ZUGFeRD Account custom mapping “BuyerIBAN” OR settings.IbanCustomFieldMappingField | Debited account identifier — BT‑91 | Prefer ZUGFeRD custom mapping; settings‑based approach is deprecated and scheduled for removal. |
| Is correction invoice | ZUGFeRD Invoice custom mapping OR ZugferdSettings Invoice Correction Flag Custom Field Mapping | Invoice type code — BT‑3 | Prefer ZUGFeRD custom mapping; settings‑based approach is deprecated and scheduled for removal. |
Related to