XRechnung Attachments: Embedding PDFs with Base64 (BG-24)

XRechnung attachments travel inside the XML file itself. Each supporting document sits in business group BG-24 and is embedded as Base64 text in BT-125, together with a MIME code and a file name. Allowed types are PDF, PNG, JPEG, CSV, XLSX and ODS. All mandatory VAT details must still be in the XML, not only in the attachment.

Last reviewed: September 2026 · This article is general information, not tax advice.

This guide covers when attachments are needed, the fields of BG-24, what an attachment looks like in UBL and CII, the limits of the federal invoice platform, and how to encode, embed and extract files. For the structure of the whole file, see XRechnung XML structure. More developer topics are collected under developer tools.

When does an XRechnung need an attachment?

An XRechnung is a data record, not a document with pages. Anything else the recipient needs to check the invoice (in German: rechnungsbegründende Unterlagen, supporting documents) travels as an attachment in the same file. Typical cases:

• Timesheets for consulting and other services, for example a breakdown of the hours billed. Freelancers will find more in e-invoicing for freelancers.
• Delivery notes and proof of service that back up the invoiced quantity.
• Measurement records (Aufmaß) in construction. For public construction contracts, the federal platform's FAQ says the contracting authority's review period only starts once the verifiable invoice has arrived together with its supporting documents. Trade businesses will find practical advice in e-invoicing for tradespeople.
• Exemption certificates (Freistellungsbescheinigung), for which XRechnung has no dedicated field. The federal platform asks for them as an attachment.
• Contracts for recurring services. Under the BMF letter of 15 October 2025, for rent or maintenance one e-invoice for the first period is enough if the underlying contract is attached.

What may go into the attachment, and what may not?

The key source is the BMF letter of 15 October 2025 (opens in a new tab) (in German, paragraph 35) from the German Federal Ministry of Finance. All mandatory VAT details under §§ 14 and 14a of the German VAT Act (UStG) must be in the structured part of the e-invoice. A mere reference in the XML to an attachment that contains those details is not enough, because the invoice could then not be processed electronically. Supplementary details may go into an embedded attachment; the letter's own example is a breakdown of timesheets in a PDF file. A link to an external target meets neither § 14(1) sentence 3 UStG nor § 31(1) of the VAT Implementing Regulation (UStDV).

The description of the service in the XML must also allow the supply to be identified clearly and checked easily on its own. A line reading "Consulting as per attachment" does not do that. "Consulting, Project Alpha, 15 hours, September 2026" in the line, with the day-by-day breakdown in the PDF, meets both requirements.

Before sending, you can run the German invoice requirements checker to see whether all details required by § 14(4) UStG are present.

Which fields does BG-24 contain?

In EN 16931 the group is called ADDITIONAL SUPPORTING DOCUMENTS. It may occur several times, once per document.

Two pitfalls concern the document type code. In CII every attachment needs ram:TypeCode with the value 916. Code 130 marks the invoiced object identifier BT-18 instead, and an attachment with code 130 fails rules CII-DT-021 and CII-DT-022. In UBL, the same element cac:AdditionalDocumentReference with cbc:DocumentTypeCode 130 also carries BT-18. Put that code on an attachment and the validator reports UBL-CR-666 and UBL-CR-673.

What does an attachment look like in UBL?

In UBL, cac:AdditionalDocumentReference comes after cbc:BuyerReference and any order or contract references, but before cac:ProjectReference and cac:AccountingSupplierParty. The example shows an embedded PDF and an external reference. The Base64 text is shortened; the "…" marks the cut.

<cbc:BuyerReference>991-12345-73</cbc:BuyerReference>
<cac:AdditionalDocumentReference>
  <cbc:ID>TS-2026-09</cbc:ID>                                               <!-- BT-122 -->
  <cbc:DocumentDescription>Timesheet September 2026</cbc:DocumentDescription> <!-- BT-123 -->
  <cac:Attachment>
    <cbc:EmbeddedDocumentBinaryObject mimeCode="application/pdf"
        filename="timesheet-2026-09.pdf">JVBERi0xLjcKJeLjz9MK…</cbc:EmbeddedDocumentBinaryObject> <!-- BT-125 -->
  </cac:Attachment>
</cac:AdditionalDocumentReference>
<cac:AdditionalDocumentReference>
  <cbc:ID>MEAS-17</cbc:ID>
  <cbc:DocumentDescription>Measurement record, section 2</cbc:DocumentDescription>
  <cac:Attachment>
    <cac:ExternalReference>
      <cbc:URI>https://example.com/documents/measurement-17.pdf</cbc:URI>  <!-- BT-124 -->
    </cac:ExternalReference>
  </cac:Attachment>
</cac:AdditionalDocumentReference>
<cac:AccountingSupplierParty>…</cac:AccountingSupplierParty>

We ran the complete sample invoice, with a PDF, a CSV and a link attachment, through KoSIT validator 1.5.0 and the XRechnung 3.0.2 validator configuration; the verdict was accept.

What does an attachment look like in CII?

In CII the attachment belongs in ram:ApplicableHeaderTradeAgreement, after the parties and any order or contract references. Inside ram:AdditionalReferencedDocument the order is ram:IssuerAssignedID, ram:URIID, ram:TypeCode, ram:Name, ram:AttachmentBinaryObject.

<ram:ApplicableHeaderTradeAgreement>
  <ram:BuyerReference>991-12345-73</ram:BuyerReference>
  <ram:SellerTradeParty>…</ram:SellerTradeParty>
  <ram:BuyerTradeParty>…</ram:BuyerTradeParty>
  <ram:AdditionalReferencedDocument>
    <ram:IssuerAssignedID>TS-2026-09</ram:IssuerAssignedID>                  <!-- BT-122 -->
    <ram:TypeCode>916</ram:TypeCode>
    <ram:Name>Timesheet September 2026</ram:Name>                            <!-- BT-123 -->
    <ram:AttachmentBinaryObject mimeCode="application/pdf"
        filename="timesheet-2026-09.pdf">JVBERi0xLjcKJeLjz9MK…</ram:AttachmentBinaryObject> <!-- BT-125 -->
  </ram:AdditionalReferencedDocument>
</ram:ApplicableHeaderTradeAgreement>

In our tests the KoSIT rules did not flag a missing filename in CII, while UBL does (UBL-DT-07). Set the attribute anyway: without a name the recipient cannot store the file sensibly, and BR-DE-22 checks uniqueness through exactly this attribute.

Which file types and rules does the validator check?

We reproduced the following messages with the same validator version:

According to the specification, file names must be unique regardless of upper and lower case, and the file extension is part of the check. So pick names that differ by more than capitalisation, and an extension that matches the MIME code. Our e-invoice validator applies these checks with the official KoSIT rules and explains every message; the codes are also described under xrechnung validation errors. Other frequent problems are covered in How to fix XRechnung validation errors.

The Extension XRechnung for XML attachments

XML attachments, typically GAEB files in construction, require the Extension XRechnung, which may be used since 1 January 2021. BT-24 is then urn:cen.eu:en16931:2017#compliant#urn:xeinkauf.de:kosit:xrechnung_3.0#conformant#urn:xeinkauf.de:kosit:extension:xrechnung_3.0. With this identifier the KoSIT rules accept application/xml (BR-DEX-01). The attached XML must not itself contain elements that embed further XML documents, and sender and recipient should agree on its use in advance. According to specification 3.0.2, the Extension has its own syntax binding for UBL Invoice only, but XML attachments can also be used in CII.

What limits apply on the federal OZG-RE platform?

Since the consolidation on 19 September 2025, the OZG-RE has been the only invoice-receipt platform of the German federal government. Its FAQ (opens in a new tab) (in German) sets these rules for attachments: they must be embedded Base64-encoded in the invoice file and must not be sent as separate e-mail attachments. Allowed extensions are png, pdf, jpg, jpeg, xlsx, ods and csv, plus xml with the Extension. An invoice may contain at most 200 embedded documents, and active content such as macros is not allowed.

The FAQ is not consistent on every figure. Plan with the smallest value and add the Base64 overhead. Agree on a link to "Große Anlagen" with the recipient in advance: if the authority cannot open it, the invoice can be rejected as not verifiable. The federal states and municipalities run their own portals with their own rules.

What does Base64 do to a file?

Base64, defined in RFC 4648 (opens in a new tab), represents arbitrary bytes with 64 printable characters: A–Z, a–z, 0–9, + and /, with = as padding at the end. Every three bytes become four characters. This is necessary because a PDF contains bytes that are not allowed in XML, such as null bytes and control characters, or that have a meaning there, such as < and &.

• Size: the file grows by about 33 percent. 3 MB becomes 4 MB, 7.5 MB becomes about 10 MB. Under a 10 MB limit, the PDF itself must stay well below 10 MB.
• Not encryption: anyone can decode Base64 without a key. An attachment is as readable as the invoice itself.
• Standard alphabet: the XML data type base64Binary only knows the standard alphabet. Base64url with - and _, as used in web tokens, fails the XSD.
• Line breaks: the schema allows whitespace inside Base64 text, but strict decoders reject line breaks; in Java, Base64.getDecoder() fails and only Base64.getMimeDecoder() skips them. Encode without line breaks.

You can often recognise the file type from the first characters of the Base64 text. If they do not match the mimeCode, something is wrong.

Our base64 decode tool runs in the browser and works on text. It is handy for encoding a short CSV attachment (non-ASCII characters are treated as UTF-8) or checking the start of a Base64 block: JVBERi0xLjcK decodes to %PDF-1.7. For binary files such as PDFs, use the commands in the next section.

How do I embed an attachment, step by step?

1. Prepare the file. Use an allowed format without macros. Give it a descriptive, unique file name with the right extension and no path, for example timesheet-2026-09.pdf.
2. Encode it. Produce Base64 text without line breaks, for example with one of the commands below.
3. Insert BG-24. Place the block at the position shown above. A good BT-122 is an identifier that the invoice text refers to; BT-123 is a short description.
4. Check the size. Compare the size of the finished XML file with the limit of your channel.
5. Validate. Check the file before sending, for example with our xrechnung viewer. BR-52, BR-CL-24 and BR-DE-22 show up there. Keep the validation report.
6. Send and archive. The attachment is part of the XML file. Archive the XML unchanged in its original form, as described in e-invoice archiving in Germany.

# Linux (GNU coreutils), no line breaks
base64 -w 0 timesheet-2026-09.pdf > timesheet.b64

# macOS (does not wrap unless you pass -b)
base64 -i timesheet-2026-09.pdf -o timesheet.b64

# Windows PowerShell
[Convert]::ToBase64String([IO.File]::ReadAllBytes("$PWD\timesheet-2026-09.pdf")) | Set-Content -NoNewline timesheet.b64

In code, one line is enough:

import base64, pathlib
b64 = base64.b64encode(pathlib.Path("timesheet-2026-09.pdf").read_bytes()).decode("ascii")

const b64 = require("fs").readFileSync("timesheet-2026-09.pdf").toString("base64");

String b64 = Base64.getEncoder().encodeToString(Files.readAllBytes(Path.of("timesheet-2026-09.pdf")));

Our xrechnung generator produces the invoice data as UBL or ZUGFeRD but does not embed attachments. Add the BG-24 block in your invoicing software or with a script; in the generator's UBL output it goes directly after cbc:BuyerReference.

How do I extract attachments from an XRechnung?

To inspect the file, open it in the XML viewer, which also runs in the browser. The tree shows each attachment with its reference, description, MIME code and file name. To save the files, a short script that understands both syntaxes is enough:

import base64, pathlib, sys
import xml.etree.ElementTree as ET

TAGS = {
    "{urn:oasis:names:specification:ubl:schema:xsd:CommonBasicComponents-2}EmbeddedDocumentBinaryObject",
    "{urn:un:unece:uncefact:data:standard:ReusableAggregateBusinessInformationEntity:100}AttachmentBinaryObject",
}

for el in ET.parse(sys.argv[1]).iter():
    if el.tag in TAGS:
        name = pathlib.Path(el.get("filename") or "attachment.bin").name
        data = base64.b64decode("".join((el.text or "").split()), validate=True)
        pathlib.Path(name).write_bytes(data)
        print(f"{name}: {el.get('mimeCode')}, {len(data)} bytes")

The script strips whitespace before decoding and stops on invalid Base64. Path(...).name discards any path in the filename attribute, so a manipulated invoice with a name like ../../file cannot write outside the working folder. The extracted files are working copies; the original remains the unchanged XML file.

How do attachments work in ZUGFeRD?

ZUGFeRD uses the same CII syntax for its XML part. Depending on the profile, supporting documents can therefore sit in the XML as ram:AdditionalReferencedDocument with ram:AttachmentBinaryObject, exactly as shown above. A ZUGFeRD invoice is also a PDF/A-3, which can technically embed further files. For VAT purposes, the BMF letter of 15 October 2025 makes the structured XML part decisive; if the PDF view differs, the XML prevails. Whether a recipient processes extra files in the PDF container automatically depends on their software. Embedding inside the XML is therefore the less ambiguous route, and if you send ZUGFeRD in the XRECHNUNG profile to federal authorities, follow the OZG-RE attachment rules.

To see which files a ZUGFeRD PDF contains, use our tool to extract XML from PDF files: it pulls out the invoice XML and lists the names of any other embedded files. You can then validate the extracted XML in the viewer. The comparison XRechnung vs. ZUGFeRD explains how the two formats differ, and What is ZUGFeRD? covers profiles and versions.