Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

ZUGFeRD

Synchronisation scope

Synchronisation
Direction
When it runs

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

Profile
Validator
Notes

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

Younium Field
ZUGFeRD descriptor

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

Younium Field
ZUGFeRD party

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:

Condition
Payment means code

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.

Younium Field
ZUGFeRD party

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

Younium Field
ZUGFeRD line

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.

Tax category
Reason text
VATEX code

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

Younium Field
ZUGFeRD totals

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:

Order
Source
Notes

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

Condition
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.

Mapping target
ZUGFeRD field
Use

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?