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.
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-Invoice | MIDbridgeX E-Invoice | |
|---|---|---|
| Trigger | Chargebee calls MIDbridgeX as its e-invoicing provider | job "Create e-invoice" after the document import, scheduled or as part of a process chain |
| Data source | structured document data from Chargebee (no PDF) | imported documents (Chargebee, other billing systems, file import) |
| Format selection | specified by Chargebee per document, otherwise the default format | one format per job; several jobs for several formats |
| Document selection | every document for which Chargebee has enabled e-invoicing | time period plus AND-combined rules (country, customer type, document type, any field, "no e-invoice yet") |
| Sending | Chargebee by email | document sending in MIDbridgeX or your existing process |
| Status in Chargebee | visible on the invoice | not affected |
| Suited for | all invoicing in Chargebee | several 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).
| Format | Use | Syntax | Legally binding original | Countries |
|---|---|---|---|---|
| Factur-X / ZUGFeRD EN 16931 profile | B2B | UN/CEFACT CII | PDF/A-3b with embedded factur-x.xml | DE, AT, CH, FR |
| XRechnung 3.0 | B2G Germany (Leitweg-ID, the German public-sector routing ID, required) | UN/CEFACT CII | the XML file; PDF is a visual copy only | DE |
| Peppol BIS Billing 3.0 | B2B/B2G via the Peppol network | OASIS UBL 2.1 | the XML file; PDF is a visual copy only | EU-27, NO, IS |
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.
- 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).
- 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
FAILEDand a reason – so the reason appears directly in Chargebee. - 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.
- Status feedback. MIDbridgeX actively reports
SUCCESSorFAILEDback to Chargebee. Failed reports are retried at increasing intervals. - Retrieval. Chargebee retrieves the finished document (base64-encoded, no publicly reachable storage URL) and attaches it to the invoice.
- 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.
| Method | Path | Purpose |
|---|---|---|
| POST | /spi/credentials/validate | validate credentials |
| GET | /spi/health | operational status |
| GET | /spi/einvoicing/activations | supported formats per country |
| GET | /spi/einvoicing/data_input_fields | additional data (Leitweg-ID, Peppol ID) |
| POST | /spi/einvoicing/documents | submit document |
| GET | /spi/einvoicing/documents/{id}/status | processing status |
| GET | /spi/einvoicing/documents/{id}/download | finished 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.
PENDING and lists the missing fields in plain text – you see the gap in Chargebee before the first invoice fails.6Validation and mandatory data
FAILED, in the job route in the error log and, optionally, by email.Arithmetic checks before every generation
- Line amount = quantity × price − discount (BR-CO-23); the line amount comes from Chargebee's exact line total, not from the unit price truncated to two decimal places.
- Sum of line items = invoice net total (BR-CO-10); the gross total matches the header.
- The tax category of header and lines is derived in one place from country, tax amount and VAT ID (domestic, EU reverse charge, intra-community supply, non-EU). Header and lines therefore cannot diverge (BR-S/AE/G/O).
- VAT IDs carry a valid ISO country prefix (BR-CO-9); a missing prefix is added during customer import where the country makes it unambiguous.
Mandatory data for XRechnung (extract of the BR-DE rules)
| Rule | Requirement | Source in MIDbridgeX |
|---|---|---|
| BR-DE-15 | Leitweg-ID (BT-10) | sent by Chargebee, otherwise the default value from the settings |
| BR-DE-2/5/6/7 | Seller contact: name, phone, email | company data |
| BR-DE-3/4, 8/9 | Postcode and city of seller and buyer | company data or customer address |
| BR-DE-16 | Seller's tax number or VAT ID | company data |
| BR-DE-1 | Payment means | with IBAN: credit transfer (code 58), otherwise code 1 |
| BT-34 / BT-49 | Electronic address of seller / buyer | company 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.
- Robust assignment: Storage is keyed by document number and document type, not by an internal ID. It survives a re-import of the document, and also the case where Chargebee requests the e-invoice before the document has been imported into MIDbridgeX.
- One e-invoice per document: If several format jobs run, none overwrites another's invoice; foreign entries are skipped and counted.
- DATEV: The e-invoice is always included in the DATEV XML export and the DATEV document image service. The conventional document image (e.g. the Chargebee PDF) can additionally be included per format; the pure visual copy of an XRechnung never is.
- E-invoicing mandate as a block (optional): From a cut-off date, documents are still posted but only transmitted to DATEV once an e-invoice exists. The block applies uniformly to document images, XML export and EXTF posting batches.
- Customer PDF: If you produce your invoice PDFs yourself, MIDbridgeX loads them via a URL from a Chargebee custom field or a Chargebee comment and detects an embedded e-invoice in them.
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.
| Topic | Implementation |
|---|---|
| SPI key | generated server-side (256 bits of randomness), shown once, stored encrypted; grants access to the e-invoicing interface only |
| Routing | one central address for all customers; the target instance is determined by a prefix in the key – without a matching key, no instance responds |
| Verification | constant-time comparison; rate-limited validation endpoint; optionally the Chargebee merchant ID must match |
| Disabled | if the Chargebee route is switched off, all SPI paths respond with 404 |
| Transport | HTTPS only; documents as base64 in the response body, never via a public storage URL |
| Availability | generated documents can be retrieved for 30 days by default (configurable); audit-proof archiving remains the task of your archive or DATEV |
| Logging | every submission, status report and retrieval with merchant ID and trace ID |
| Backup | instance 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:
| Setting | Default | Effect |
|---|---|---|
| E-invoicing route | MIDbridgeX E-Invoice | Chargebee E-Invoice (adapter) or MIDbridgeX E-Invoice (job) |
| Offered formats | Factur-X, XRechnung | what is offered to Chargebee; Peppol can be enabled |
| Countries (comma separated) | DE | countries for which activations are reported, with only the matching formats per country |
| Format when Chargebee specifies none | Factur-X | used when Chargebee specifies none |
| Chargebee connection | – | REST connection for status reports, PDF retrieval and sending |
| Report status to Chargebee | off | without 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 days | availability 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.
10Limitations and open points
- Peppol delivery: MIDbridgeX generates Peppol documents but does not deliver them via the Peppol network. This requires a contract with a Peppol Access Point; in the Chargebee route, Chargebee can take over delivery.
- Clearance countries (Italy, Poland, Spain, France once its mandate starts) are not covered; each would be a separate integration project.
- Direct debit: SEPA mandates are not yet shown as a separate block (BG-19); the invoice states the credit-transfer details instead.
- Chargebee fields not carried over: invoice note (BT-22), trading name (BT-28), address subdivision (BT-39/54) and payment reference (BT-83).
- Leitweg-ID is not stored in the customer master data but taken per transaction from Chargebee or from the default value.
- Triggering of sending by MIDbridgeX in Chargebee is optional and should be tested on your test site before it is enabled.
Contact: MID Technologien GmbH · +49 7551 989 63 64 · info@mid-tech.de · mid-tech.de
