Zugferd - German e-invoicing compliance

Overview

To be compliant with new German e-invoicing regulations, Younium can send invoices in the Zugferd format. Zugferd is a hybrid PDF file format, which means that it consists of a visual PDF file with embedded XML data in a specified format. Read more on the Zugferd standard at https://www.ferd-net.de/en/standards/zugferd/factur-x 

 

How it works

When Zugferd invoice format is enabled, all PDF invoices will be created and stored as Zugferd PDF's. For an end-customer this will not mean anything unless they import the PDF in a Zugferd compatible system and has access to the embedded XML data. For end-customers using the traditional visible PDF file there will be no difference. However since Zugferd is a regulated structured file format it has certain requirements on data, it can mean that when you are creating an invoice you may get validation error messages in Younium that required data is missing and this needs to be added before posting the invoice. More on this in the "Required data" section.

When posting an invoice, Younium created the PDF according to the existing template but also injects the Zugferd XML file into the PDF before sending it further to email and saving the file on the invoice record in Younium. Zugferd file is added using the EN 16931 Extended profile.

 

How to enable ZUGFeRD

  • Enable “Attach ZUGFeRD XML to invoice” in Settings > Invoices > Invoice settings.
  • Enable “Attach ZUGFeRD XML to invoice” on the customer Account (Account details).
  • Optional default: In Settings > Accounts > Account settings, set “Attach ZUGFeRD XML to invoice” (default) to auto‑enable for new accounts.
    ZUGFeRD XML is attached to posted invoice PDFs only when both the global setting and the Account flag are enabled.

Required data 

Extended profile

  • Legal entity address and country: Populates Seller details.
  • Buyer Invoice address and country: Populates Buyer details and country code.
  • Seller VAT (conditional): Must be valid for non‑domestic tax; for domestic tax it’s optional but validated if present.
  • Buyer VAT (conditional): Required/validated when buyer tax is required (based on line/tax context).
  • Invoice number, date, currency: Required.
  • Payment info: Total, Subtotal, and Due date required.
  • Each line item: Description, Unit code, Unit quantity, Net unit price, Billed quantity, Line total amount, Tax type, Tax category, and Tax percent required.

ZUGFeRD settings

Location: Settings > Integrations > ZUGFeRD settings

  • Enable IBAN: Includes Seller IBAN from the invoice’s bank account (if missing we try to use Legal entity IBAN value if present).
  • Enable BIC: Includes Seller BIC from the invoice’s bank account (if missing we try to use Legal entity BIC value if present).
  • Zugferd Custom Mappings:
    Choose Custom field to be mapped to one of allowed fields. Supported custom field types: Invoice or Account. Value of mapped custom field will be used to populated chosen allowed field in Zugferd data.
  • IBAN custom field mapping (Account):
    Deprecated - can be done using Zugferd Custom Mappings feature.
    Choose an Account custom field to populate Buyer IBAN in the XML. When set, payment means becomes SEPA Credit Transfer; if the field has a value, Buyer IBAN is included.
  • “Is correction invoice” custom field mapping (Invoice):
    Deprecated - can be done using Zugferd Custom Mappings feature.
    Choose an Invoice checkbox custom field. When set to true on an invoice, the invoice is treated as a Correction, regardless of cancel/credit status.

Custom mappings

Steps:

  1. Create a custom field on either invoice or account level 
    Navigate to Settings > General > Custom fields
    Create a custom field called e.g. "Zugferd buyer reference"
  2. Navigate to Settings > Integrations > Zugferd settings
    View, add, update or remove custom mappings. 
  3. Click "Add new" to add a custom mapping field - whether you choose Invoice or Account depends on what level you created the custom field on. This step will enable you to select what custom field should be matched to what integration field.
    As of now, there are three integration fields allowed.

    Select the previously created Younium custom field (in the previous example called "Zugferd buyer reference" and map it towards the integration field "Buyer reference".
    Save the change

  4. Navigate to an invoice, edit it and enter a value in the custom field

  5. When generating the Zugferd PDF, it will now hold a value in "Buyer reference"

Custom mappings allowed fields

Allowed fields (Integration fields):

  • Buyer reference - Invoice Custom Mapping
  • Buyer reference - Account Custom Mapping
  • Is Correction Invoice
  • Buyer IBAN

Note:

If user decides to use Account Custom Mapping and also Invoice Custom Mapping for the same Allowed field we are treating it as follows:

  • Account Mapping Value is used as general/global value assigned to Zugferd data
  • If also present Invoice Mapping Value it overrides Account Mapping value for assigned Zugferd data

Invoice types

  • Invoice: Default when not credit/correction.
  • Credit note: When the invoice is a credit or has a negative total.
  • Correction: When the invoice is cancelled, or when the configured “Is correction invoice” custom field is true.

Implemented features

  • Cancellation receipt reference in XML: Includes a reference with ID "CR-{InvoiceNumber}", issue date = invoice date, and Reference type code = "AWR". This is populated consistently to aid downstream processes.
  • Credit note referencing: For credit invoices, the XML includes an InvoiceReferencedDocument that links back to the original (debit) invoice. The referenced document ID is set to the original invoice number and the IssueDateTime to the original invoice date. If invoice references exist, the debit invoice is preferred; otherwise the value falls back to Current Invoice number.

Examples

  • Configure Buyer IBAN from Account custom field:
    1) Create or select an Account custom field that will hold IBAN, and fill it for the customer.
    2) In ZUGFeRD settings, Add Account Custom Mapping, choose Account custom field and choose "Buyer IBAN" integration field.
    3) Result: Payment means becomes SEPA Credit Transfer; if the Account field has a value, Buyer IBAN is included in the XML.
  • Configure Correction via Invoice custom field:
    1) Create an Invoice checkbox custom field (e.g., “Is correction invoice”).
    2) In ZUGFeRD settings, Add Invoice Custom Mapping, choose Invoice custom field and choose "Is Correction Invoice" integration field.
    3) Set the field to true on any invoice to produce a Correction invoice with cancellation references, regardless of credit status.