ZUGFeRD
Synchronisation scope
Invoices and credit notes (XML embedded in the PDF)
Younium → ZUGFeRD
Whenever an invoice PDF is generated for a legal entity with ZUGFeRD enabled
Not in scope: transmission to a network or recipient, received (supplier) invoices.
Overview
The ZUGFeRD integration embeds structured invoice XML (CII format, ZUGFeRD 2.3) inside PDF documents using the extended profile by default. Younium builds an InvoiceDescriptor from invoice and legal entity data, validates basic or extended models, serialises XML, and attaches it to the PDF as ZUGFeRD-invoice.xml with MIME type text/xml and AF relationship Alternative.
Authentication
There is no external connection and nothing to authenticate. The ZUGFeRD XML is embedded inside Younium when an invoice PDF is generated for a legal entity that has ZUGFeRD enabled.
Profiles supported
Basic, Comfort
Supported
Documents are built to the Extended profile by default
Extended
Supported
The default profile
Minimum, BasicWL, XRechnung, XRechnung1, EReporting
Not available
Selecting one of these does not produce a document
Saved XML uses ZUGFeRDVersion.Version23, format CII, embedded filename ZUGFeRD-invoice.xml.
Eligibility and line filtering
Invoice lines are filtered with FilterInvoiceLinesForDocument using invoice type and InvoiceSettings before modelling (same pattern as other document outputs). Validation exceptions surface as ZugferdValidationException.
General information mapping
Invoice.InvoiceNumber
Invoice number
Invoice.InvoiceDate
Invoice date
Invoice.Currency.Code
Currency (must match supported enum mapping)
Invoice.Notes
Note on descriptor
Credit or negative total
InvoiceType.CreditNote (document type 381)
Any other invoice
InvoiceType.Invoice (document type 380)
Explicit correction flag with a resolved preceding invoice
InvoiceType.Correction (document type 384); see Credit notes and corrections
Fixed
Business process urn:fdc:peppol.eu:2017:poacc:billing:01:1.0
Party mapping — seller
ApplicationLegalEntity name, address, tax IDs
Seller party block
Invoice bank account (the account matching the invoice currency), otherwise ApplicationLegalEntity.IBAN, BIC
Seller payment account
Seller payment account
The legal entity's IBAN and BIC are used only when the invoice carries no bank account of its own. When the invoice has a bank account, that account is used as it stands and no field is borrowed from the legal entity, so a currency-specific account with a blank BIC or IBAN never inherits the legal entity's value. Wrong bank details are worse than none, because the buyer pays and nothing flags the error.
The IBAN and BIC are included only when the corresponding settings in the ZUGFeRD integration settings are on. The account number of the bank account is always included. A payment account is written whenever an IBAN or an account number is available; a BIC on its own is not written. An account with an account number but no IBAN is sent with the account number only, and no empty IBAN element is left in the XML.
The payment means type code is derived from this seller account, never from the buyer's account:
Invoice currency is EUR and the seller IBAN starts with the country code of a SEPA country
58 — SEPA credit transfer
Seller account present in any other case (non-euro currency, IBAN outside SEPA, no IBAN)
30 — Credit transfer
No seller account
1 — Instrument not defined
Invoices without a seller account carry code 1 (the payment means group stays present, as EN 16931 requires).
Note on SEPA countries: SEPA eligibility is decided by the first two characters of the seller IBAN, after trimming surrounding spaces, against the European Payments Council list of SEPA scheme countries. The check does not validate the IBAN itself. A value that is not an IBAN is treated as a plain credit transfer.
Remittance information
The payment reference shown to the payer is the invoice's OCR number when the invoice has one, and the invoice number otherwise.
Party mapping — buyer
The buyer address (street, postcode, city) is taken from the invoice's own address — the same address printed on the invoice PDF. If the invoice has no address of its own, Younium falls back to the account's default invoice address. The buyer country is read only from the invoice address and does not use this fallback.
Invoice.InvoiceAddress, falling back to Invoice.Account.DefaultInvoiceAddress
Buyer street, postcode, city
Invoice.InvoiceAddress country
Buyer country code
Invoice.Account.Name
Buyer name
Domestic vs cross-border
Affects tax category on lines (isDomesticTransaction)
Note on buyer address vs. buyer country: The buyer address falls back to the account's default invoice address when the invoice has none, but the buyer country never does — it always comes from the invoice address, since it also decides the domestic/foreign VAT category on the invoice.
Optional buyer IBAN from the buyer IBAN mapping on the account. When the mapping supplies an IBAN it replaces the buyer IBAN fallback in the ZUGFeRD settings, so the document carries a single debtor account. The buyer IBAN is written as the buyer's account for direct debit and does not affect the payment means code.
The invoice does not name a separate payee. Previously the buyer was written as the payee, which instructed the receiver to pay itself; the payee is now omitted, so payment goes to the seller.
Line item mapping
Line net amounts, quantity, product/charge text
Trade line items
TaxItems
Tax category per line (see VAT exemption reasons below)
Extended profile
Additional extended line fields
Tax breakdown groups by category and VAT rate; discrepancies between line tax sum and invoice tax are logged as warnings.
VAT exemption reasons
The same reason text and code are used for a tax category wherever it appears — on the invoice-level VAT breakdown and on every line carrying that category — so the two always agree.
E — Exempt from VAT
Exempt from VAT
—
G — Export outside the EU
Export outside the EU
VATEX-EU-G
AE — Reverse charge
Reverse charge
VATEX-EU-AE
K — Intra-Community supply
Intra-Community supply
VATEX-EU-IC
S — Standard rate
None
None
Z — Zero rate
None
None
Note on standard and zero-rated invoices: EN 16931 forbids a VAT exemption reason on a standard-rated or zero-rated invoice line or breakdown. Younium omits the reason entirely for categories S and Z, so a domestic invoice at the standard or zero rate validates correctly against the KoSIT validator and equivalents.
Payment and totals mapping
Sum of line nets
lineTotalAmount
Invoice tax total
taxTotalAmount
Grand total
grandTotalAmount
Amount due
duePayableAmount
Rounded to two decimals with away-from-zero rounding.
Credit notes and corrections
Preceding invoice
A credit note or correction references the invoice it relates to (the preceding invoice number and date). Younium never references the document itself. It resolves the preceding invoice from the first of these sources that yields a value:
1
The link created when a credit is raised with Credit invoice
Credits only. It comes first because Credit invoice copies the original invoice's custom fields onto the credit, so a preceding invoice number mapped from them describes what the original corrected, not what the credit credits.
2
The PrecedingInvoiceNumber and PrecedingInvoiceDate mappings (invoice scope)
The only source for credits from change orders and for corrections. If only the number is mapped, the date is taken from the issued invoice with that number. If no date can be found, the date is left out rather than guessed.
3
None
The document carries no preceding invoice reference. The reference is optional in EN 16931.
Document type
The correction flag is set and a preceding invoice resolves
Correction (384), whether or not the invoice is a credit. A flagged credit is a correction of the invoice it credits.
The correction flag is set but no preceding invoice resolves
Invoice (380) or credit note (381), and a warning is logged
Credit or negative total
Credit note (381)
Anything else, including cancelled invoices
Invoice (380)
The correction flag is the IsCorrectionInvoice mapping (invoice scope) or, for tenants that still use it, the custom field configured in the ZUGFeRD settings (IsCorrectionInvoiceCustomFieldMappingField, truthy values true, 1, yes, y, on). If both are set the document still carries one reference. A cancelled invoice is not treated as a correction, because only draft invoices can be cancelled and a cancelled invoice was therefore never issued.
Note on timing: Mapped values are read when the PDF is rendered. A value added after an invoice is posted appears when the invoice is downloaded again, not in the PDF stored at posting. Set the mappings before posting.
SEPA direct debit
When the account has a SEPA mandate on a EUR invoice, the payment means is SEPA direct debit (code 59) instead of the default credit transfer. The mandate comes from account-scope mappings.
SepaMandateReference
Mandate reference (BT-89)
A mandate on a EUR invoice selects direct debit
SepaCreditorId
Creditor identifier (BT-90)
Required with a mandate
BuyerIBAN
Debited account (BT-91)
The buyer's IBAN
A mandate without a creditor identifier stops document generation with a validation message that names the missing value, because XRechnung requires it with code 59. A mandate on an invoice in any other currency is ignored. Accounts without a mandate keep the existing payment means.
Custom fields
Correction flag uses a configured field configuration ID; renaming the underlying custom field without updating settings breaks correction detection.
Allowed custom mapping targets are constrained by ZugferdAllowedFieldsProvider (integration maintenance).
Last updated
Was this helpful?