Alle Anleitungen

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:

ScopeWofürPflicht
invoices:writeRechnung anlegen, festschreiben, Zahlung erfassenja
invoices:readPDF abholenfür Schritt 4
customers:writeKunde im Adressbuch anlegenoptional
customers:readvorhandenen Kunden nachschlagenoptional
webhooks:writeWebhook-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 Kreis RE-<Jahr>-<laufende Nummer>, zum Beispiel RE-2026-0124. Führst du ein anderes Schema, gib number selbst mit; ist die Nummer schon vergeben, antwortet die API mit 409 conflict.
  • sender: Name, Anschrift, Steuernummer und Bankverbindung kommen aus Absender in deinem Konto. Felder, die du im Body mitschickst, haben Vorrang.
  • invoice_date und service_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, t ist 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 wie created_at). Sie fällt entlang sequence nie, 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-Key 24 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 der id) und schreibst nur noch fest.
  • PATCH /invoices/{id}/status kennt keinen Idempotency-Key. Ein zweites sent auf eine festgeschriebene, noch offene Rechnung antwortet mit 200. Ist die Zahlung schon erfasst (partial oder paid), kommt 409 conflict: Werte das im Neulauf als erledigt.

Fehler richtig behandeln

Jeder Fehler ist JSON: { "error": { "code", "message", "details"? } }.

CodeHTTPReaktion
unauthorized401Key fehlt/abgelaufen/widerrufen: Alarm, nicht wiederholen.
forbidden403Kein Business-Tarif oder Scope fehlt: Konfiguration prüfen.
invalid_request400Body kein gültiges JSON oder Pflichtangabe fehlt: Datenaufbau prüfen.
not_found404Die id gibt es in diesem Konto nicht: Zuordnung prüfen.
validation_failed422Pflichtfeld/Format: details[] auswerten, nicht wiederholen.
conflict409Nummer vergeben, Beleg festgeschrieben, schon bezahlt, Idempotency-Drift.
rate_limited429Retry-After abwarten, dann erneut (Default 120 Req./Min./Key).
server_error500mit Backoff wiederholen.
service_unavailable503nachgelagerter 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, dann stripe trigger checkout.session.completed.
  • MaxRechnung-Rückkanal: POST /api/v1/webhooks/{id}/test (Scope webhooks:write) oder im UI Testzustellung senden im Menü am Endpunkt schickt sofort einen signierten webhook.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 von X-Webhook-Signature-V2 (oder X-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) und small_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 /invoices nicht. In der E-Rechnung steht als Land des Empfängers deshalb DE.
  • Refunds und Teilstornos bildet MaxRechnung als Korrektur oder Storno ab (/invoices/{id}/corrections, /invoices/{id}/cancellations), nicht durch Löschen. Ein charge.refunded-Handler ist ein sinnvoller nächster Schritt, aber nicht Teil dieser Anleitung.
  • Fremd-IDs wie stripe_customer_id legst 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.