Blog-Übersicht
Engineering · Billing ≈ 8 Min. Lesezeit

Stripe-Integration für Webseite & SaaS: Subscriptions, Webhooks und Idempotenz richtig bauen

Von Ayoub Boubakri · 09Clicks · Veröffentlicht am

Stripe ist nicht „eine Library installieren und fertig“. Wer es so behandelt, baut sich nach 6 Monaten Inkonsistenzen, verlorene Subscriptions und Buchhaltungs-Drama. Wer es richtig macht, hat ein Billing-System, das nachts ohne Eingriff läuft. Hier ist, wie wir Stripe in Production bauen – inklusive der Lessons aus Renzom.

  • Stripe
  • SaaS
  • Webhooks
  • Idempotenz
  • DSGVO

Warum Stripe-Integration trügerisch einfach ist

Die Stripe-Dokumentation ist exzellent. Genau das ist die Falle: Sie suggeriert, dass „Subscriptions in 50 Zeilen Code“ ein Production-System sind. Sind sie nicht. Ein echtes SaaS- oder E-Commerce-System muss mindestens vier Klassen von Edge-Cases überleben:

  • Doppelte Webhooks: Stripe re-tried bei Timeout. Ihr Endpoint muss idempotent sein.
  • Out-of-order Events: customer.subscription.updated kann vor customer.subscription.created ankommen.
  • Stripe = Source-of-Truth, DB = Cache: Wenn beide auseinanderlaufen, verliert immer Ihre DB.
  • Test-Mode-vs-Live: Webhook-Secrets, Customer-IDs, Pricing – alles ist getrennt. Saubere Env-Trennung ist Pflicht.

Ignorieren Sie diese vier, und Ihr Billing wird in den Support-Tickets landen, die Sie nie sehen wollten.

Architektur: drei Schichten, klar getrennt

Wir bauen Stripe-Integrationen mit drei sauber getrennten Schichten:

  1. Frontend (Checkout / Portal): Stripe-Checkout oder Customer-Portal als gehostete Stripe-Seiten. So selten wie möglich Custom-UI für Karten – das spart PCI-Scope und Wartung.
  2. API (Webhook-Receiver): Eigener Endpoint, der Webhook-Signatur prüft, Events in eine Queue stellt und sofort 200 zurückgibt. Keine Geschäftslogik im Receiver.
  3. Worker (Event-Handler): Verarbeitet Events idempotent, schreibt in DB, triggert Side-Effects (Provisioning, Mail, Discord-Ping). Mit Retry und Dead-Letter-Queue.

Diese Trennung ist der Unterschied zwischen einem Stripe-Setup, das Sie schlafen lässt, und einem, das beim ersten Stripe-Outage panisch piept.

Idempotenz: das wichtigste Feature, das niemand erklärt

Stripe garantiert „at-least-once“-Delivery. Heißt: Bei Netzwerkproblemen schickt Stripe denselben Webhook erneut. Wenn Ihr Code dann nochmal einen Server provisioniert oder eine Mail rausschickt, haben Sie ein Problem.

Lösung: Jedes Event hat eine id. Speichern Sie diese in einer stripe_event_log-Tabelle mit Unique-Constraint. Wenn das Insert fehlschlägt, war das Event schon verarbeitet. Punkt.

Bei Renzom nutzen wir genau dieses Muster: Webhook-Receiver schreibt das Event in stripe_event_log, Worker liest, checkt processed_at, verarbeitet, setzt processed_at = NOW(). Selbst wenn der Worker während der Verarbeitung crashed, ist die nächste Iteration safe.

Subscription-Lifecycle: die Events, die wirklich zählen

Sie brauchen nicht alle 130+ Stripe-Events. In Production reichen meist diese:

  • checkout.session.completed – User hat bezahlt, Provisioning starten.
  • customer.subscription.created / .updated / .deleted – Subscription-State spiegeln.
  • invoice.paid / invoice.payment_failed – Recovery-Workflows triggern.
  • customer.subscription.trial_will_end – Reminder vor Trial-Ende.

Alles andere ist meist Noise. Tipp: Nur Events abonnieren, die Sie wirklich verarbeiten. Sonst füllen Sie Ihre Logs mit Müll.

Customer-Portal: das hidden Killer-Feature

Stripe’s Customer-Portal ist meist unterschätzt. Sie schicken Kunden mit einer signierten URL hin, dort können sie:

  • Zahlungsdaten ändern
  • Subscriptions upgraden / downgraden
  • Rechnungen herunterladen
  • Subscription kündigen (mit „dunning“-Recovery falls gewünscht)

Das ist ein kostenloser, gehosteter Bereich, den Sie sonst selbst bauen müssten. Er erspart Ihnen Stunden Frontend-Arbeit und ist DSGVO-konform für die meisten Standard-Fälle.

Wenn Sie es spielerischer wollen: Sie können das Portal mit Stripe-Konfiguration brandsen (Logo, Farben, Sprache).

DSGVO: Was Sie wirklich beachten müssen

Stripe ist ein US-Unternehmen. Das macht Sie nicht automatisch DSGVO-illegal, aber Sie brauchen drei Dinge:

  • AVV mit Stripe: Liegt automatisch via Stripe-Dashboard vor.
  • Drittland-Hinweis im Datenschutz: Stripe Inc., Hinweis auf US-Datenübermittlung, Standardvertragsklauseln (SCCs).
  • Cookie-Banner: Stripe-Skripte, die für Risk-Scoring nötig sind, sollten korrekt klassifiziert werden („technisch erforderlich“ ist hier oft tragbar, sauberer ist Consent-Mode).

Tipp: Stripe bietet eine EU-Adresse für Stripe Payments Europe Ltd (Dublin). Das macht den AVV-Pfad einfacher. In der Datenschutz-Erklärung beide Entitäten erwähnen.

Steuern: Stripe Tax oder eigene Logik?

Wenn Sie B2C-Subscriptions in EU verkaufen, fällt OSS-Mehrwertsteuer an (One-Stop-Shop). Sie haben drei Optionen:

  • Stripe Tax: Bezahltes Add-on. Berechnet automatisch korrekte MwSt. pro Land. Empfehlenswert ab ~50 EU-Kunden.
  • Manuelle Tax-Rates: Sie pflegen MwSt.-Sätze pro Land selbst. Rentabel bei kleinem EU-Umsatz, gefährlich bei wachsender Kundenzahl.
  • Kleinunternehmer (§ 19 UStG): Wenn Sie unter der Schwelle bleiben, gar keine MwSt. ausweisen. Klare Notiz in den AGB. Das ist der Modus, in dem 09Clicks selbst rechnet.

Häufige Fehler, die wir in Migrationen sehen

  • Webhook-Endpoint ohne Signatur-Check (offen für Spoofing).
  • Geschäftslogik direkt im Webhook-Receiver (ohne Queue) – fragil bei Last.
  • Keine stripe_event_log-Tabelle – Re-Tries verursachen Doppel-Aktionen.
  • Customer-IDs zwischen Test-Mode und Live durcheinander – zerstört Migrationen.
  • Subscription-Status nicht in DB gespiegelt – jede Anzeige fragt Stripe live ab und kostet Latenz.
  • Refunds nicht auf Provisioning gespiegelt – Kunde wird refundiert, hat aber weiter Zugang.

Wann Stripe das richtige Tool ist (und wann nicht)

Stripe ist ideal für:

  • SaaS-Subscriptions (monatlich / jährlich) – das Brot-und-Butter-Use-Case.
  • One-Off-Käufe mit globalem Markt (gehostete Checkouts, Apple/Google Pay).
  • Marketplace-Modelle (Stripe Connect).

Stripe ist nicht ideal für:

  • Klassischer DACH-Mittelstand mit Rechnung + SEPA-Lastschrift als Hauptweg → Mollie oder Adyen sind oft passender.
  • Reine B2B-Verkäufe ohne Self-Serve-Flow → ggf. einfache Zahlungslinks reichen.

Fazit: Stripe ist Engineering, nicht „Plug-In“

Eine saubere Stripe-Integration ist vergleichbar mit dem Bau eines kleinen Mini-Backends. Sie können das in 3–4 Tagen Engineer-Zeit erledigen, wenn Sie es richtig machen – oder in 3 Wochen Support-Hölle, wenn Sie die Idempotenz-Schicht weglassen.

Bei 09Clicks ist Stripe-Integration Teil des Engineering-Pakets. Wir bauen den vollen Pfad: Checkout → Webhooks → Worker → Provisioning → Customer-Portal → DSGVO-Texte. Und wir haben den Stack ein paar Mal in Production durchgespielt – zuletzt bei Renzom.

Brauchen Sie eine saubere Stripe-Integration?

Ob SaaS-Subscriptions oder One-Off-Checkout – wir bauen Stripe-Setups, die in einem Jahr noch konsistent sind.

Stripe-Integration anfragen Pakete & Preise Renzom-Case ansehen

Ähnliche Artikel