MIDbridge
Technical description

E-Invoicing with Chargebee
and MIDbridgeX

Architecture, data flows, formats, validation rules, security and configuration of e-invoice generation for Chargebee customers.

Contents

1Overview
6Validation and mandatory data
2Architecture
7Storage on the document and DATEV
3The two operating modes
8Security and operations
4Formats
9Configuration
5Flow via the Chargebee interface
10Limitations and open points
DocumentVersion 1.0 · November 2026
AudienceIT, accounting and project leads at Chargebee customers
PublisherMID Technologien GmbH
mid-tech.de

1Overview

MIDbridgeX turns your Chargebee invoices and credit notes into standard-compliant e-invoices according to EN 16931 – as Factur-X/ZUGFeRD, XRechnung or Peppol BIS Billing 3.0.

The documents are stored on the invoice document, can be passed to DATEV, and are either sent to your customers by Chargebee itself or provided by MIDbridgeX. This document is intended for IT, accounting and project leads at companies that use Chargebee and have to comply with the e-invoicing mandate.

What the solution does

  • Generation in three formats from one shared data model
  • Two operating modes: Chargebee triggers generation (Chargebee E-Invoice), or MIDbridgeX generates on its own after import (MIDbridgeX E-Invoice)
  • Validation of all mandatory data before generation – an invalid document is never produced
  • Storage on the document and hand-over to DATEV (XML export or DATEV document image service)
  • Your own invoice layout (document designer) or your familiar Chargebee PDF as the carrier

What it does not do

  • Delivery via the Peppol network: this requires a certified Peppol Access Point.
  • Clearance and reporting via government platforms (Italy SDI, Poland KSeF, Spain Verifactu, France PDP).
  • Legal advice: which obligation applies in which country is a question for your tax advisor.

2Architecture

Chargebee delivers documents to MIDbridgeX either directly via the SPI interface or through the regular document import. Both routes end in the same generation core; the result is always stored on the document and passed on to DATEV from there.

MIDbridgeX instance (one per customer) Import ChargebeeInvoice issued Document importChargebee, web shop,file import SPI adapterChargebee E-Invoice Generation jobMIDbridgeX E-Invoice Generation core Check mandatory dataCreate XML (CII/UBL)PDF/A-3 or visual copy EN 16931 ChargebeeStatus, retrieval,sending to customer Stored on documentDocument tree, sending DATEVXML export, images
Figure 1 – Two entry points, one generation core. Status feedback to Chargebee exists only in the Chargebee route.

3The two operating modes

A single switch in Settings → E-invoicing ("E-invoicing route") determines who triggers generation. Both routes use the same generation core, the same validation rules and the same storage on the document.

Chargebee E-InvoiceMIDbridgeX E-Invoice
TriggerChargebee calls MIDbridgeX as its e-invoicing providerjob "Create e-invoice" after the document import, scheduled or as part of a process chain
Data sourcestructured document data from Chargebee (no PDF)imported documents (Chargebee, other billing systems, file import)
Format selectionspecified by Chargebee per document, otherwise the default formatone format per job; several jobs for several formats
Document selectionevery document for which Chargebee has enabled e-invoicingtime period plus AND-combined rules (country, customer type, document type, any field, "no e-invoice yet")
SendingChargebee by emaildocument sending in MIDbridgeX or your existing process
Status in Chargebeevisible on the invoicenot affected
Suited forall invoicing in Chargebeeseveral sources, custom rules, independence from Chargebee's e-invoicing

Switching between the two routes is a setting, not a rebuild – like all settings in MIDbridgeX, it is made only together with us as administrators. E-invoices already generated remain on the document.

4Formats

All three formats are based on EN 16931. Factur-X/ZUGFeRD and XRechnung are produced by the same CII generator with a profile parameter, Peppol by a dedicated UBL generator – both share the common calculation rules (amounts, tax categories, rounding).

FormatUseSyntaxLegally binding originalCountries
Factur-X / ZUGFeRD
EN 16931 profile
B2BUN/CEFACT CIIPDF/A-3b with embedded factur-x.xmlDE, AT, CH, FR
XRechnung 3.0B2G Germany (Leitweg-ID, the German public-sector routing ID, required)UN/CEFACT CIIthe XML file; PDF is a visual copy onlyDE
Peppol BIS Billing 3.0B2B/B2G via the Peppol networkOASIS UBL 2.1the XML file; PDF is a visual copy onlyEU-27, NO, IS
Rule of thumb. If you invoice businesses in Germany, Austria and Switzerland, Factur-X/ZUGFeRD is sufficient. XRechnung is added as soon as German public authorities are invoice recipients. Peppol becomes relevant when recipients require it or have a Peppol inbox.

Credit notes are supported in all formats (CII type code 381 or UBL CreditNote).

PDF carrier for Factur-X

Either MIDbridgeX generates the PDF in its own layout designed in the document designer (colours, font, logo, texts in German/English), or the familiar Chargebee PDF is taken over and enriched with the XML. In the second case MIDbridgeX checks the external PDF first – all fonts embedded, no encryption, no JavaScript, no existing attachments – and adds the colour profile and PDF/A metadata. If it fails the check, no e-invoice is produced; there is no silent fallback to a different layout.

5Flow via the Chargebee interface

MIDbridgeX is registered in Chargebee as the e-invoicing provider "MIDbridgeX" and implements Chargebee's E-Invoicing Service Provider Interface (SPI). The flow is asynchronous: Chargebee receives an acknowledgement immediately, the document is produced afterwards.

  1. Submission. When a document in Chargebee is ready for billing, Chargebee sends it to MIDbridgeX as structured data (parties, line items, tax totals, payment means).
  2. Acknowledgement. MIDbridgeX checks authentication and amounts and confirms within the 250 ms required by Chargebee. A document with content errors is not answered with an HTTP error but with the status FAILED and a reason – so the reason appears directly in Chargebee.
  3. Generation. In the background, mandatory data is checked, XML and PDF are generated and stored. Documents interrupted by a restart mid-generation are resumed automatically.
  4. Status feedback. MIDbridgeX actively reports SUCCESS or FAILED back to Chargebee. Failed reports are retried at increasing intervals.
  5. Retrieval. Chargebee retrieves the finished document (base64-encoded, no publicly reachable storage URL) and attaches it to the invoice.
  6. Sending. Chargebee sends the e-invoice to your customer. Optionally, MIDbridgeX actively triggers sending per format.

Interfaces

All paths are located under the central MIDbridgeX SPI address stored in Chargebee's provider description.

MethodPathPurpose
POST/spi/credentials/validatevalidate credentials
GET/spi/healthoperational status
GET/spi/einvoicing/activationssupported formats per country
GET/spi/einvoicing/data_input_fieldsadditional data (Leitweg-ID, Peppol ID)
POST/spi/einvoicing/documentssubmit document
GET/spi/einvoicing/documents/{id}/statusprocessing status
GET/spi/einvoicing/documents/{id}/downloadfinished document

The return path to Chargebee (status report, retrieval of the Chargebee PDF, triggering of sending) uses a standard REST connection with your Chargebee site API key. No separate OAuth onboarding is required.

Diagnostics in Chargebee. If mandatory seller data is missing (e.g. phone or tax number), the activation reports the status PENDING and lists the missing fields in plain text – you see the gap in Chargebee before the first invoice fails.

6Validation and mandatory data

Principle: better no e-invoice than an invalid one. If mandatory data is missing or the amounts do not add up, no document is produced; the reason is reported with a reference to the standard (BT/BR number) – in Chargebee as FAILED, in the job route in the error log and, optionally, by email.

Arithmetic checks before every generation

Mandatory data for XRechnung (extract of the BR-DE rules)

RuleRequirementSource in MIDbridgeX
BR-DE-15Leitweg-ID (BT-10)sent by Chargebee, otherwise the default value from the settings
BR-DE-2/5/6/7Seller contact: name, phone, emailcompany data
BR-DE-3/4, 8/9Postcode and city of seller and buyercompany data or customer address
BR-DE-16Seller's tax number or VAT IDcompany data
BR-DE-1Payment meanswith IBAN: credit transfer (code 58), otherwise code 1
BT-34 / BT-49Electronic address of seller / buyercompany email; buyer email or Leitweg-ID

Mandatory data for Peppol

Peppol endpoints of seller and buyer (BT-34/BT-49) and a buyer reference. The seller endpoint comes from the settings, the buyer's from Chargebee; if it is missing, it is derived from the VAT ID and flagged as a warning, because it is not verified whether the recipient is registered under it.

Seller data from two sources

Identity (name, address, tax numbers) comes from Chargebee's business entity, contact and bank details from the company data in MIDbridgeX. If the names differ, a warning is shown.

7Storage on the document and DATEV

Every e-invoice generated is stored on the document – regardless of which route produced it. Document tree, document sending and DATEV hand-over read it from there.

8Security and operations

Each customer receives a dedicated, isolated MIDbridgeX instance with its own database, its own file storage and its own encryption key. Data of different customers never shares a table.

TopicImplementation
SPI keygenerated server-side (256 bits of randomness), shown once, stored encrypted; grants access to the e-invoicing interface only
Routingone central address for all customers; the target instance is determined by a prefix in the key – without a matching key, no instance responds
Verificationconstant-time comparison; rate-limited validation endpoint; optionally the Chargebee merchant ID must match
Disabledif the Chargebee route is switched off, all SPI paths respond with 404
TransportHTTPS only; documents as base64 in the response body, never via a public storage URL
Availabilitygenerated documents can be retrieved for 30 days by default (configurable); audit-proof archiving remains the task of your archive or DATEV
Loggingevery submission, status report and retrieval with merchant ID and trace ID
Backupinstance backups AES-256-encrypted by default

9Configuration

Setting up the Chargebee route takes two steps: generate an SPI key in MIDbridgeX and enter it in Chargebee for the provider MIDbridgeX. No address needs to be entered anywhere. All other items are settings in MIDbridgeX:

Can only be carried out together with a MIDbridgeX administrator. The settings in MIDbridgeX can only be reached with administrator access. You cannot carry out key generation and these settings yourself – they are made together with us, the administrators at MID Technologien.
SettingDefaultEffect
E-invoicing routeMIDbridgeX E-InvoiceChargebee E-Invoice (adapter) or MIDbridgeX E-Invoice (job)
Offered formatsFactur-X, XRechnungwhat is offered to Chargebee; Peppol can be enabled
Countries (comma separated)DEcountries for which activations are reported, with only the matching formats per country
Format when Chargebee specifies noneFactur-Xused when Chargebee specifies none
Chargebee connection–REST connection for status reports, PDF retrieval and sending
Report status to Chargebeeoffwithout a report, Chargebee does not retrieve the document
Chargebee PDF as basis–per format: Chargebee layout instead of own layout
Also send Chargebee PDF to DATEV–per format
Trigger sending in Chargebee–per format, after the status report has been confirmed
Fallback Leitweg-ID–fallback if Chargebee sends none
Seller's Peppol endpoint–own Peppol ID, otherwise derived from the VAT ID
Generated documents retrievable (days)30 daysavailability for retrieval
Expected Chargebee site (optional)–if set ⇒ must match on every call

Job "Create e-invoice" (MIDbridgeX route)

Format, PDF basis (own layout or existing PDF), time period (all, since last run, last n days, document date), AND-combined selection rules, and a summary email listing documents that do not yet have an e-invoice. A dry run shows in advance which documents would be generated and which would fail, and why.

Prerequisite for both routes: maintained company data (name, address, phone, email, tax number or VAT ID, IBAN) and complete customer addresses.

10Limitations and open points

Recommendation before go-live: for each format, validate one generated invoice and one credit note with your real data against the KoSIT validator (XRechnung/Factur-X) or the Peppol BIS Schematron. We support this as part of the onboarding project.

Contact: MID Technologien GmbH · +49 7551 989 63 64 · info@mid-tech.de · mid-tech.de