MaxRechnung an Stripe anbinden
Aus jeder bezahlten Stripe-Transaktion automatisch eine festgeschriebene MaxRechnung-Rechnung erzeugen, mit API-Key, Scopes, Idempotency und signierten Webhooks in beide Richtungen.
12 Min. LesezeitStand 26. Oktober 2026
Voraussetzungen: Business-Tarif (öffentliche API), ein Stripe-Konto
Inhalt
Stripe kassiert die Zahlung, MaxRechnung schreibt die Rechnung dazu: Für jede erfolgreiche Stripe-Zahlung entsteht automatisch ein festgeschriebener Beleg in deinem MaxRechnung-Konto, fortlaufend nummeriert in deinem Nummernkreis, mit deutschem Layout und als E-Rechnung (XRechnung / ZUGFeRD). So liegen alle Rechnungen an einer Stelle, auch die aus Stripe-Zahlungen.
Die Anbindung läuft über die öffentliche REST-API (/api/v1, Business-Tarif).
Einen fertigen „Stripe-Button" gibt es nicht; du betreibst ein kleines
Verbindungsstück (ein paar Dutzend Zeilen), das Stripe-Webhooks entgegennimmt und
die passenden MaxRechnung-Endpunkte aufruft. Diese Anleitung zeigt es Schritt für
Schritt mit Beispielcode (Node / TypeScript).
Der Datenfluss
Kunde zahlt bei Stripe
│
▼
[1] Stripe-Webhook ──► dein Connector
Ereignis: checkout.session.completed (oder invoice.paid)
│
▼
[2] Connector ruft MaxRechnung /api/v1 auf:
POST /customers optional, ins Adressbuch
POST /invoices Rechnung als Entwurf
PATCH /invoices/{id}/status { "status": "sent" } → festschreiben
POST /payments Zahlung erfassen → Status "paid"
│
▼
[3] MaxRechnung ──► dein Connector (signierter Webhook zurück)
Ereignis: invoice.finalized (und invoice.paid)
│
▼
[4] Connector holt den fertigen Beleg:
GET /invoices/{id}/pdf → an den Stripe-Kunden hängen / per Mail
Zwei Richtungen:
- Stripe → MaxRechnung: dein Connector reagiert auf Stripe-Events und legt den Beleg an.
- MaxRechnung → dein System: MaxRechnung meldet per signiertem Webhook zurück, sobald der Beleg festgeschrieben bzw. bezahlt ist: der Auslöser, um das PDF abzuholen.
Voraussetzungen
- Business-Tarif in MaxRechnung (schaltet die öffentliche API und die Webhooks frei). Verlässt das Konto den Business-Tarif, werden alle API-Keys widerrufen und die Webhook-Endpunkte pausiert. Nach einem erneuten Wechsel zu Business legst du neue Keys an und aktivierst die Endpunkte wieder.
- Deine Absenderdaten unter Absender (Name, Anschrift, Steuernummer oder USt-IdNr., Bankverbindung): die API übernimmt sie in jede Rechnung.
- Ein Stripe-Konto mit Zugriff auf Webhooks und die Stripe-CLI.
- Eine kleine, öffentlich erreichbare HTTPS-Anwendung als Connector (Serverless oder Container, hier ein Express-Handler).
Schritt 1: API-Key mit minimalen Scopes
Den Key legst du in der App an: Einstellungen, Reiter API, Karte
Öffentliche API. Trag einen Namen ein, wähle die Gültigkeit, hake die
Scopes an und klick auf Key erstellen. Der Key wird einmalig im Klartext
angezeigt (mxr_live_…) und danach nur noch als Präfix. Vergib genau die Scopes,
die der Connector braucht:
| Scope | Wofür | Pflicht |
|---|---|---|
invoices:write | Rechnung anlegen, festschreiben, Zahlung erfassen | ja |
invoices:read | PDF abholen | für Schritt 4 |
customers:write | Kunde im Adressbuch anlegen | optional |
customers:read | vorhandenen Kunden nachschlagen | optional |
webhooks:write | Webhook-Endpunkte per API verwalten (sonst im UI) | optional |
invoices:write schließt invoices:draft mit ein, aber nicht
invoices:read: Ohne den Lese-Scope antwortet der PDF-Abruf mit 403. Den
Rückkanal-Webhook (Schritt 4) legst du am einfachsten einmalig im UI an; dann
braucht der Automatik-Key kein webhooks:write.
Leg den Key als Umgebungsvariable ab, niemals in den Code:
export MAXRECHNUNG_API_KEY=mxr_live_xxxxxxxxxxxxxxxxxxxxxxxx
export MAXRECHNUNG_API_BASE=https://maxrechnung.de/api/v1
Jeder Request trägt den Key im Header:
Authorization: Bearer mxr_live_xxxxxxxxxxxxxxxxxxxxxxxx
Schritt 2: Stripe-Events empfangen
Richte in Stripe (oder per CLI) einen Webhook auf deinen Connector ein und abonniere das Ereignis, das zu deinem Bezahl-Flow passt:
- Stripe Checkout:
checkout.session.completed - Stripe Billing / Rechnungen:
invoice.paid - Payment Intents pur:
payment_intent.succeeded
Prüfe die Stripe-Signatur, bevor du irgendetwas tust, sonst kann jeder deinem Connector Belege unterschieben:
import express from "express";
import Stripe from "stripe";
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const app = express();
app.post("/stripe/webhook", express.raw({ type: "application/json" }), async (req, res) => {
let event: Stripe.Event;
try {
event = stripe.webhooks.constructEvent(req.body, req.headers["stripe-signature"] as string, process.env.STRIPE_WEBHOOK_SECRET!);
} catch {
return res.status(400).send("bad signature");
}
// Sofort 200 an Stripe, Arbeit im Hintergrund; Stripe erwartet Antwort
// in wenigen Sekunden, sonst wiederholt es.
res.json({ received: true });
if (event.type === "checkout.session.completed") {
// Das Event trägt keine Positionen: Stripe liefert line_items nur per expand.
const { id } = event.data.object as Stripe.Checkout.Session;
const session = await stripe.checkout.sessions.retrieve(id, { expand: ["line_items"] });
await createMaxRechnungInvoice(event.id, session);
}
});
Schritt 3: Aus dem Stripe-Event eine Rechnung bauen
Vier Aufrufe. Die POST-Endpunkte nehmen einen Idempotency-Key; leite ihn
aus der Stripe-Event-ID (evt_…) ab, damit eine wiederholte Zustellung nichts
doppelt anlegt. Jeder Aufruf braucht einen eigenen Wert (evt_…,
evt_…:cus, evt_…:pay): MaxRechnung merkt sich zum Key auch Endpunkt und Body,
derselbe Wert an einem anderen Endpunkt endet mit 409 conflict.
3a: Kunde ins Adressbuch (optional)
Für den reinen Rechnungslauf nicht nötig: POST /invoices trägt den Empfänger
inline. Ein Kunde lohnt sich, wenn du im Adressbuch nachschlagen oder
E-Rechnungs-Vorgaben (Käuferreferenz, Steuerregelung) pflegen willst.
Damit der Connector einen Stripe-Kunden wiederfindet, leg unter
Einstellungen → Eigene Felder ein Textfeld mit dem Schlüssel
stripe_customer_id an und hake Kunden an. Die API sucht dann nach dem
Wert, eine eigene Zuordnungstabelle brauchst du nicht:
const stripeId = session.customer as string | null;
const found = stripeId ? await mxr("GET", `/customers?custom_fields[stripe_customer_id]=${encodeURIComponent(stripeId)}`) : { data: [] };
const customer =
found.data[0] ??
(await mxr("POST", "/customers", event.id + ":cus", {
name: session.customer_details?.name ?? "Unbekannt",
address: formatAddress(session.customer_details?.address),
email: session.customer_details?.email ?? "",
country: session.customer_details?.address?.country ?? "DE",
custom_fields: stripeId ? { stripe_customer_id: stripeId } : {},
}));
Eigene Felder sind nur intern: Sie stehen weder im PDF noch in der E-Rechnung.
Ein Schlüssel, den das Konto nicht kennt, endet mit 422 (im Body) bzw. 400
(im Filter). Welche Felder es gibt, liefert GET /custom-fields.
3b: Rechnung als Entwurf
Stripe-Beträge sind Bruttobeträge in Cent → price_mode: "gross" und Euro als
Dezimalzahl (eine Zahl, kein String). Den USt-Satz je Position musst du selbst
setzen (19, 7 oder 0); wenn du Stripe Tax nutzt, übernimm den dortigen
Satz.
Der Rechnungsbetrag ist dann die Summe der Bruttopreise und deckt sich mit dem
Stripe-Betrag, auch bei einer E-Rechnung (e_invoice_formats).
const line_items = (session.line_items?.data ?? []).map(li => ({
description: li.description ?? "Leistung",
quantity: li.quantity ?? 1,
unit_price: (li.amount_total ?? 0) / 100 / (li.quantity ?? 1),
vat_rate: 19,
}));
const draft = await mxr("POST", "/invoices", event.id, {
payment_term_days: 0, // schon bezahlt
price_mode: "gross",
recipient: {
name: session.customer_details?.name ?? "Unbekannt",
address: formatAddress(session.customer_details?.address),
email: session.customer_details?.email ?? "",
},
line_items,
notes: `Zahlung über Stripe (${session.id}).`,
});
Was im Body fehlt, ergänzt die API:
number: MaxRechnung vergibt die nächste Nummer im KreisRE-<Jahr>-<laufende Nummer>, zum BeispielRE-2026-0124. Führst du ein anderes Schema, gibnumberselbst mit; ist die Nummer schon vergeben, antwortet die API mit409 conflict.sender: Name, Anschrift, Steuernummer und Bankverbindung kommen aus Absender in deinem Konto. Felder, die du im Body mitschickst, haben Vorrang.invoice_dateundservice_date: ohne Angabe das heutige Datum.
Antwort: 201 mit dem Rechnungsobjekt inkl. id, number und totals. Prüfe,
dass totals.gross dem Stripe-Betrag (session.amount_total / 100) entspricht;
Rundungsdifferenzen bei der Rückrechnung des Einzelpreises fängst du hier ab.
Soll der Beleg eine E-Rechnung sein, setz zusätzlich e_invoice_formats
(["xrechnung"], ["zugferd"] oder beide). Das Festschreiben prüft dann auch
deren Pflichtangaben, zum Beispiel die E-Mail-Adresse des Empfängers.
Ansprechpartner, Telefon und Land des Absenders stehen unter Absender im
Block Für die E-Rechnung (XRechnung / ZUGFeRD). Die Dateien liefern
GET /invoices/{id}/xrechnung und GET /invoices/{id}/zugferd (Scope
invoices:read). Ist das ZUGFeRD-PDF noch nicht fertig, antwortet der
Endpunkt mit 202 und MaxRechnung meldet invoice.zugferd_ready, sobald es
bereitliegt.
3c: Festschreiben
Der Statuswechsel draft → sent durchläuft den § 14-Vollständigkeitscheck und löst
invoice.finalized aus; bei einer E-Rechnung friert er zusätzlich das XML ein.
Eigener Endpoint, eigener Scope: PATCH /invoices/{id}/status braucht den
vollen invoices:write-Scope (Entwurfsänderungen über PATCH /invoices/{id}
kommen mit dem kleineren invoices:draft aus).
await mxr("PATCH", `/invoices/${draft.id}/status`, undefined, { status: "sent" });
Kommt hier 422 validation_failed, ist im Entwurf noch ein Pflichtfeld offen;
details[] nennt Feld und Grund. Meldet 409 conflict, dass die Rechnung
zwischenzeitlich geändert wurde, wiederholst du den Aufruf. Danach ist der
Beleg unveränderlich; Korrekturen laufen über POST /invoices/{id}/corrections, Stornos über
POST /invoices/{id}/cancellations.
3d: Zahlung erfassen
await mxr("POST", "/payments", event.id + ":pay", {
invoice_id: draft.id,
amount: (session.amount_total ?? 0) / 100,
note: `Stripe ${session.payment_intent}`,
});
Ohne paid_on (JJJJ-MM-TT) gilt der heutige Tag. MaxRechnung leitet den
Rechnungsstatus aus der Zahlungssumme ab (sent → partial → paid) und meldet
payment.recorded sowie, bei Vollzahlung, invoice.paid. Ist die Rechnung
schon ganz bezahlt, antwortet die API mit 409 conflict. Ein Betrag über dem
offenen Rest braucht das Feld overpayment: credit weist das Guthaben aus,
ignore erfasst nur den Rest. Ohne das Feld kommt 422 validation_failed.
Die Helfer
async function mxr(method: string, path: string, idemKey?: string, body?: unknown) {
const res = await fetch(process.env.MAXRECHNUNG_API_BASE + path, {
method,
headers: {
Authorization: `Bearer ${process.env.MAXRECHNUNG_API_KEY}`,
"Content-Type": "application/json",
...(idemKey ? { "Idempotency-Key": idemKey } : {}),
},
body: body ? JSON.stringify(body) : undefined,
});
if (!res.ok) {
const err = await res.json().catch(() => ({}));
throw Object.assign(new Error(err?.error?.message ?? res.statusText), {
status: res.status,
code: err?.error?.code,
details: err?.error?.details,
});
}
return res.status === 204 ? null : res.json();
}
// Anschrift als Text, Zeilen mit \n getrennt: "Rosenweg 8\n50999 Köln"
function formatAddress(a?: Stripe.Address | null) {
if (!a) return "";
return [a.line1, a.line2, `${a.postal_code ?? ""} ${a.city ?? ""}`.trim()].filter(Boolean).join("\n");
}
Schritt 4: Rückkanal MaxRechnung-Webhooks
Damit dein System weiß, wann der Beleg fertig ist, registrierst du einmalig
einen Webhook-Endpunkt: im UI unter Einstellungen, Reiter Webhooks
(Adresse eintragen, Events anhaken, Endpunkt hinzufügen) oder per API. Die
Adresse muss mit https:// beginnen und öffentlich erreichbar sein. Je Konto
sind höchstens 10 Endpunkte möglich, je Ereignis höchstens 3.
const hook = await mxr("POST", "/webhooks", "setup:stripe-sync", {
url: "https://connector.example.com/maxrechnung/webhook",
events: ["invoice.finalized", "invoice.paid"],
});
// hook.secret ("whsec_…") liefert die API nur in dieser Antwort, sicher ablegen.
// Im UI zeigt das Menü am Endpunkt es über "Secret anzeigen" erneut.
Jede Zustellung ist ein POST mit dem Body
{ id, type, created_at, created, sequence, data }; bei
invoice.*-Ereignissen ist data gleich { invoice, changes } mit der ganzen
Rechnung, bei payment.* gleich { payment, changes }. Ausnahme ist
invoice.zugferd_ready mit { invoice_id, job_id, profile }. Signiert wird
mit HMAC-SHA256, zwei Header:
X-Webhook-Signature-V2: t=<unix>,v1=<hex>— HMAC über<t>.<Rohtext des Bodys>mit deinem Endpunkt-Secret,tist die Unix-Sekunde des Zustellversuchs. Nimm nur an, was höchstens fünf Minuten alt ist; ein mitgeschnittener Request lässt sich dann nicht später wieder einspielen.X-Webhook-Signature: sha256=<hex>— die ältere Form über den Rohtext allein, ohne Zeit. Bleibt für bestehende Empfänger erhalten.
Jede Zustellung kommt „mindestens einmal“: ein Wiederholungsversuch trägt
dieselbe Event-id im Body (und X-Webhook-Id), aber ein frisches t.
Merke dir verarbeitete ids, dann richtet ein Doppel keinen Schaden an.
Prüfe konstantzeitig:
import { createHmac, timingSafeEqual } from "node:crypto";
function verify(secret: string, rawBody: string, header?: string, toleranceSec = 300): boolean {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header ?? "");
if (!m) return false;
const [, t, v1] = m;
const expected = createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(v1);
if (a.length !== b.length || !timingSafeEqual(a, b)) return false;
return Math.abs(Math.floor(Date.now() / 1000) - Number(t)) <= toleranceSec;
}
const seen = new Set<string>(); // in echt: Tabelle oder Cache mit Ablauf
app.post("/maxrechnung/webhook", express.raw({ type: "application/json" }), async (req, res) => {
if (!verify(process.env.MXR_WEBHOOK_SECRET!, req.body.toString(), req.headers["x-webhook-signature-v2"] as string)) {
return res.status(401).end();
}
const evt = JSON.parse(req.body.toString());
if (seen.has(evt.id)) return res.json({ ok: true, duplicate: true });
seen.add(evt.id);
res.json({ ok: true });
if (evt.type === "invoice.finalized") {
const pdf = await fetch(`${process.env.MAXRECHNUNG_API_BASE}/invoices/${evt.data.invoice.id}/pdf`, {
headers: { Authorization: `Bearer ${process.env.MAXRECHNUNG_API_KEY}` },
});
const bytes = Buffer.from(await pdf.arrayBuffer());
// an den Stripe-Kunden hängen, per E-Mail schicken, im DMS ablegen …
}
});
Verfügbare Ereignisse: invoice.created, invoice.updated, invoice.finalized,
invoice.partially_paid, invoice.paid, invoice.cancelled, invoice.deleted,
payment.recorded, payment.cancelled, correction.created,
invoice.zugferd_ready. Zustellung mit exponentiellem Backoff und Dead-Letter
übernimmt MaxRechnung; dein Endpunkt muss nur zügig 2xx antworten.
Weiterleitungen folgt MaxRechnung nicht. Eine Zustellung kann mehrfach ankommen:
Merke dir evt.id und überspring Wiederholungen.
Eine Reihenfolge garantiert MaxRechnung nicht. Zustellungen laufen parallel,
und nach einem Ausfall deines Endpunkts kann invoice.paid vor
invoice.finalized ankommen. Deshalb trägt jedes Ereignis zwei Ordnungswerte,
die beim Entstehen vergeben werden und bei jeder Wiederholung gleich bleiben:
sequence: eine Nummer, die je Konto streng steigt. Lücken sind normal, etwa wenn ein Ereignis nur an einen anderen Endpunkt ging.created: die Unix-Sekunde, in der das Ereignis entstand (dieselbe Zeit wiecreated_at). Sie fällt entlangsequencenie, mehrere Ereignisse können aber dieselbe Sekunde tragen.
Wer in Reihenfolge verarbeiten muss, sortiert nach sequence. Merkst du dir je
Rechnung die zuletzt verarbeitete Nummer, erkennst du auch einen veralteten
Stand: Kommt ein Ereignis mit kleinerer sequence an, überschreibt es nichts.
Idempotenz & Wiederholungen
- Stripe stellt Events mehrfach zu (Netzfehler, Timeouts). MaxRechnung
speichert die Antwort je
Idempotency-Key24 Stunden und spielt sie bei gleichem Endpunkt und Body identisch zurück (Idempotency-Replayed: true). Danach gilt der Key als neu: Eine spätere Wiederholung legt einen zweiten Beleg an. Merke dir verarbeitete Event-IDs deshalb auch in deinem System. - Nutze als Key die Stripe-Event-ID (
evt_…) für den Rechnungsschritt und ein Suffix je weiterem Aufruf (evt_…:cus,evt_…:pay). Dann ist der ganze Ablauf pro Event genau einmal wirksam, auch bei paralleler Zustellung. - Gleicher Key + abweichender Body oder anderer Endpunkt →
409 conflict. Das heißt: Du hast den Key wiederverwendet und dabei die Nutzdaten geändert; nicht blind wiederholen, sondern loggen und den Datenaufbau prüfen. - Fällt dein Connector zwischen 3b und 3c aus, findest du den Entwurf beim
Neulauf über denselben Idempotency-Key wieder (Replay der
201-Antwort mit derid) und schreibst nur noch fest. PATCH /invoices/{id}/statuskennt keinen Idempotency-Key. Ein zweitessentauf eine festgeschriebene, noch offene Rechnung antwortet mit200. Ist die Zahlung schon erfasst (partialoderpaid), kommt409 conflict: Werte das im Neulauf als erledigt.
Fehler richtig behandeln
Jeder Fehler ist JSON: { "error": { "code", "message", "details"? } }.
| Code | HTTP | Reaktion |
|---|---|---|
unauthorized | 401 | Key fehlt/abgelaufen/widerrufen: Alarm, nicht wiederholen. |
forbidden | 403 | Kein Business-Tarif oder Scope fehlt: Konfiguration prüfen. |
invalid_request | 400 | Body kein gültiges JSON oder Pflichtangabe fehlt: Datenaufbau prüfen. |
not_found | 404 | Die id gibt es in diesem Konto nicht: Zuordnung prüfen. |
validation_failed | 422 | Pflichtfeld/Format: details[] auswerten, nicht wiederholen. |
conflict | 409 | Nummer vergeben, Beleg festgeschrieben, schon bezahlt, Idempotency-Drift. |
rate_limited | 429 | Retry-After abwarten, dann erneut (Default 120 Req./Min./Key). |
server_error | 500 | mit Backoff wiederholen. |
service_unavailable | 503 | nachgelagerter Dienst (z. B. ZUGFeRD-Rendering): Backoff. |
Antworten tragen X-RateLimit-Limit / -Remaining / -Reset. Plane den
Connector so, dass er eine Warteschlange mit Backoff hat statt harter Retries
im Request-Handler.
Testen
- Stripe-Seite:
stripe listen --forward-to localhost:4242/stripe/webhook, dannstripe trigger checkout.session.completed. - MaxRechnung-Rückkanal:
POST /api/v1/webhooks/{id}/test(Scopewebhooks:write) oder im UI Testzustellung senden im Menü am Endpunkt schickt sofort einen signiertenwebhook.test-POST an deinen Endpunkt; damit prüfst du die Signaturprüfung, ohne einen echten Beleg zu erzeugen. Unter Signatur prüfen im selben Menü fügst du den empfangenen Rohtext und den Wert vonX-Webhook-Signature-V2(oderX-Webhook-Signature) ein und siehst, ob er zum Secret passt. - Trockenlauf: ein eigener API-Key mit kurzer Gültigkeit, am besten in einem zweiten MaxRechnung-Konto nur für Tests (die API braucht auch dort Business); kleine Beträge, danach die Belege wieder stornieren.
Grenzen
- Kein Plug-in. Das Verbindungsstück betreibst und wartest du. Diese Anleitung ist die Vorlage, kein installierbares Modul.
- Steuerlogik ist deine. Aus Stripe kommt ein Betrag, kein deutscher
Steuersatz. Das Mapping auf
vat_rate,vat_scheme(Reverse-Charge, innergemeinschaftlich, Ausfuhr, steuerfrei) undsmall_business(Kleinunternehmer) musst du setzen, siehe die Rechnungsfelder in der API-Referenz. - Empfänger im Ausland. Die Rechnung nimmt die Anschrift als Text; ein
eigenes Feld für das Land des Empfängers hat
POST /invoicesnicht. In der E-Rechnung steht als Land des Empfängers deshalbDE. - Refunds und Teilstornos bildet MaxRechnung als Korrektur oder Storno
ab (
/invoices/{id}/corrections,/invoices/{id}/cancellations), nicht durch Löschen. Eincharge.refunded-Handler ist ein sinnvoller nächster Schritt, aber nicht Teil dieser Anleitung. - Fremd-IDs wie
stripe_customer_idlegst du als eigenes Feld an (Schritt 3a). Gesucht wird nur nach dem genauen Wert, eine Teilsuche gibt es nicht.
Vollständige Endpunktliste, Schemas und ein „Ausprobieren"-Feld: /developers/api. Die maschinenlesbare Spezifikation liegt unter /api/openapi.json.
Weitere Anleitungen
Stripe ohne eigenen Server anbinden (Zapier / Make)
Stripe-Zahlungen ohne selbst betriebene Anwendung in MaxRechnung-Rechnungen verwandeln, über eine No-Code-Automation als Bindeglied. Was dabei wirklich „direkt“ geht und wo die Grenzen liegen.
9 Min.
MaxRechnung mit n8n verbinden
Vier n8n-Bausteine gegen die REST-API: Kunde anlegen, Rechnung anlegen und festschreiben, alle bezahlten Beträge aufsummieren, überfällige Rechnungen herausfiltern.
10 Min.
Die erste Rechnung in unter einer Minute
Absender, Empfänger, Position, Steuer: Schritt für Schritt zur fertigen Rechnung als PDF, ganz ohne Konto. Und wie du sie danach mit kostenlosem Konto als Entwurf speicherst.
4 Min.