Integration des Zahlungsgateways Stripe in den Checkout (Projekt Aurora)

Aus einem gesprochenen Auftrag ein strukturiertes Briefing, bereit zur Übergabe.

Beispiel einer echten Ausgabe

Zusammenfassung

Mark aus dem Zahlungsteam diktierte ein Briefing zur Anbindung des Zahlungsgateways Stripe an den Checkout des E-Shops Projekt Aurora. Ziel ist es, die aktuelle manuelle Rechnungsstellung durch Online-Kartenzahlungen zu ersetzen, mit Unterstützung für Apple Pay und Google Pay. Die Frist für den Produktiv-Rollout ist der 15. Juli, das MVP auf der Staging-Umgebung bis Ende Juni.

Detailliertes Protokoll

Was gebaut werden soll

Ziel ist es, dem bestehenden Checkout von Projekt Aurora die Kartenzahlung über Stripe hinzuzufügen. Nach dem Befüllen des Warenkorbs wählt der Kunde eine Zahlungsart und bezahlt direkt auf der Seite, ohne Weiterleitung zu einem externen Gateway. Mark betonte, dass das Zahlungsformular über Stripe Elements eingebettet werden soll, damit es im Design des E-Shops bleibt.

Neben der klassischen Karte sollen Apple Pay und Google Pay unterstützt werden, denn laut Analytics machen mobile Bestellungen über die Hälfte des Traffics aus. Barzahlung und Rechnung bleiben als Alternativen erhalten, Stripe ist nur eine dritte zusätzliche Option.

Technische Anforderungen und Absicherungen

Entscheidend ist die Zuverlässigkeit der Zahlungsbestätigung. Der Bestellstatus darf sich niemals auf Basis der Antwort aus dem Browser ändern, sondern ausschließlich über einen Stripe-Webhook im Backend (Event payment_intent.succeeded). Mark warnte ausdrücklich vor einer Situation, in der der Kunde zahlt, aber die Verbindung abbricht und die Bestellung als unbezahlt hängen bleibt.

Jeder Aufruf muss idempotent sein (ein erneutes Ausführen erzeugt keine zweite Zahlung) über einen idempotency_key. Webhooks müssen per Signatur verifiziert werden, damit sie nicht gefälscht werden können. Für den Fall eines Stripe-Ausfalls ist ein Fallback erforderlich — der Checkout darf nicht komplett abstürzen, sondern es wird nur die Karte ausgeblendet und die übrigen Zahlungsarten angeboten.

Aufgaben

Einen Backend-Endpunkt zum Anlegen eines PaymentIntent mit Stripe erstellen (Betrag, Währung, idempotency_key). · zuständig Backend-Team · Frist bis 27. Juni hoch
Stripe Elements in den Frontend-Checkout integrieren (Karte, Apple Pay, Google Pay) im Design des E-Shops. · zuständig Frontend-Team · Frist bis 30. Juni hoch
Einen Webhook-Handler für payment_intent.succeeded und payment_intent.payment_failed mit Signaturprüfung implementieren. · zuständig Backend-Team · Frist bis 27. Juni hoch
Einen Fallback ergänzen: Bei Nichtverfügbarkeit von Stripe die Kartenzahlung ausblenden und Bar und Rechnung anbieten. · zuständig Frontend-Team · Frist bis 3. Juli mittel
Testszenarien (Erfolg, Kartenfehler, Webhook-Ausfall, doppelte Zahlung) auf der Staging-Umgebung vorbereiten. · zuständig Lucy (QA) · Frist bis 8. Juli mittel

Entscheidungen

Das Zahlungsformular wird über Stripe Elements direkt in den Checkout eingebettet, ohne Weiterleitung auf eine externe Seite. 💬 aus dem Transkript: „"Ich will es drinnen haben, im selben Design, nicht dass es den Menschen irgendwohin auf eine fremde Seite wirft."“
Die Zahlungsbestätigung wird über den serverseitigen Webhook payment_intent.succeeded gelöst, nicht über die Client-Antwort. 💬 aus dem Transkript: „"Die Quelle der Wahrheit ist der Webhook im Backend, Punkt."“
Apple Pay und Google Pay sind Teil des ersten MVP, keiner späteren Phase. 💬 aus dem Transkript: „"Behandelt Apple Pay und Google Pay als Teil der Grundausstattung, nicht als Bonus für später."“

Wichtige Erkenntnisse

Der Bestellstatus wird ausschließlich vom serverseitigen Webhook gesteuert, nicht von der Browser-Antwort — das schützt vor dem Verlust einer Zahlung bei abgebrochener Verbindung. 💬 aus dem Transkript: „"Niemals, wirklich niemals, bestätigt eine Bestellung anhand dessen, was an den Browser zurückkommt. Nur anhand des Webhooks auf dem Server."“
Mobile Bestellungen machen über 50 % des Traffics aus, deshalb sind Apple Pay und Google Pay Teil des MVP, nicht erst der zweiten Phase. 💬 aus dem Transkript: „"Über die Hälfte der Leute kauft vom Handy, also müssen Apple Pay und Google Pay sofort da sein, nicht irgendwann später."“
Bei einem Stripe-Ausfall darf der gesamte Checkout nicht kaputtgehen, nur die Kartenzahlung wird ausgeblendet, während Bar und Rechnung bleiben. 💬 aus dem Transkript: „"Wenn Stripe nicht läuft, soll nicht die ganze Kasse abstürzen. Die Karte wird einfach ausgeblendet und die Leute zahlen anders."“

Daten

15. Juli Datum Produktiv-Rollout Termin für den Start des Zahlungsgateways im Live-Betrieb.
Ende Juni Datum MVP auf Staging Eine funktionsfähige Integration, bereit zum Testen.
hoch Priorität Aufgabenpriorität Mark markierte die Kartenzahlung als blockierend für die Sommerkampagne.
über 50 % Anteil mobiler Bestellungen Grund für die Aufnahme von Apple Pay und Google Pay in das MVP.

Unklarheiten / Risiken

Es ist nicht festgelegt, ob das Speichern von Karten für wiederkehrende Zahlungen (saved cards) unterstützt werden soll oder nur Einmalzahlungen.
Mark erwähnte keinen konkreten Schwellenwert für automatische Rückerstattungen (Refund) — das muss mit dem Support-Team abgestimmt werden.
Es fiel nicht, in welchen Währungen gezahlt wird (nur CZK oder auch EUR für ausländische Kunden).

Briefing für den Umsetzer

Implementierungs-Briefing — Integration des Zahlungsgateways Stripe (Projekt Aurora)

Ziel

Dem bestehenden Checkout des E-Shops Projekt Aurora die Kartenzahlung über Stripe hinzufügen, inklusive Apple Pay und Google Pay, als dritte Zahlungsart neben Bar und Rechnung.

Umfang (Scope)

Zahlungsformular über Stripe Elements direkt in den Checkout eingebettet (keine Weiterleitung zu einem externen Gateway).
Unterstützung der Zahlungsmethoden: Karte, Apple Pay, Google Pay.
Serverseitige Zahlungsbestätigung über Webhooks (Quelle der Wahrheit = Backend, nicht der Browser).
Fallback bei Nichtverfügbarkeit von Stripe (Degradation ohne Absturz des gesamten Checkouts).

Außerhalb des Umfangs (Out of Scope)

Speichern von Karten für wiederkehrende Zahlungen (saved cards) — vorerst nicht behandelt, wartet auf eine Entscheidung.
Rückerstattungen über die Admin-Oberfläche — für das MVP genügt der Refund über das Stripe Dashboard.

Funktionale Anforderungen

Anlegen einer Zahlung
- Der Backend-Endpunkt erstellt einen PaymentIntent (Betrag, Währung, idempotency_key).
- Das Frontend fordert das client_secret an und rendert Stripe Elements.
Zahlungsbestätigung
- Den Bestellstatus ändert ausschließlich der Webhook payment_intent.succeeded.
- Die Client-Antwort dient nur zur Anzeige des "Danke"-Bildschirms, niemals zur Bestätigung der Bestellung.
Zahlungsfehler
- Webhook payment_intent.payment_failed → die Bestellung bleibt im Status "wartet auf Zahlung", der Kunde erhält die Möglichkeit, es erneut zu versuchen.
Fallback
- Bei Nichtverfügbarkeit von Stripe wird die Kartenzahlung ausgeblendet und Bar + Rechnung angezeigt. Der Checkout darf nicht komplett abstürzen.

Nicht-funktionale Anforderungen

Idempotenz: Jeder PaymentIntent-Aufruf verwendet einen idempotency_key (ein erneutes Senden erzeugt keine zweite Zahlung).
Webhook-Sicherheit: Signaturprüfung (Stripe-Signature), Ablehnung nicht verifizierter Requests.
Secrets: Stripe-API-Keys ausschließlich im GCP Secret Manager, niemals im Code oder in einer .env-Datei im Git.
Logging: Jeder Zahlungsfehler und jeder eingehende Webhook geht ins Structured Logging (Cloud Logging).

Akzeptanzkriterien

Der Kunde zahlt per Karte und die Bestellung wird erst nach Empfang des Webhooks payment_intent.succeeded als bezahlt markiert.
Apple Pay und Google Pay erscheinen auf unterstützten Geräten und funktionieren end-to-end.
Bei unterbrochener Verbindung nach der Zahlung (geschlossener Browser) wird die Bestellung dank des Webhooks trotzdem als bezahlt markiert.
Ein doppeltes Absenden der Zahlung erzeugt keine zwei Zahlungen (über den idempotency_key verifiziert).
Ein gefälschter Webhook ohne gültige Signatur wird abgelehnt (HTTP 400).
Bei einem simulierten Stripe-Ausfall geht der Checkout nicht kaputt, nur die Kartenzahlung verschwindet.

Termine

MVP auf Staging: Ende Juni
Produktiv: 15. Juli

Offene Fragen

Speichern von Karten für wiederkehrende Zahlungen — ja/nein?
Währungen: nur CZK oder auch EUR?
Schwellenwert für automatischen Refund?

Transkript-Beispiel

Mark (Auftraggeber)

Also gehen wir zu den Zahlungen über. Ich will, dass wir endlich die Kartenzahlung über Stripe in den Aurora-Checkout bekommen. Jetzt zahlen die Leute entweder bar bei der Übergabe oder per Rechnung, und das bremst uns.

Mark (Auftraggeber)

Wichtig ist, dass es drinnen bleibt, im selben Design. Kein Wegwerfen auf eine fremde Seite. Wir betten es über ihre Elements ein, damit es wie ein Teil des E-Shops aussieht.

Mark (Auftraggeber)

Und jetzt das Wichtigste. Niemals, wirklich niemals, bestätigt eine Bestellung anhand dessen, was an den Browser zurückkommt. Nur anhand des Webhooks auf dem Server. Wir hatten schon mal den Fall, dass jemand bezahlt hat, ihm die Verbindung abbrach und die Bestellung als unbezahlt hängen blieb. Das darf nicht wieder passieren.

Mark (Auftraggeber)

Behandelt Apple Pay und Google Pay als Teil der Grundausstattung, nicht als Bonus für später. Über die Hälfte der Leute kauft vom Handy, also muss es sofort da sein.

Mark (Auftraggeber)

Und noch eine Sache. Wenn Stripe nicht läuft, soll nicht die ganze Kasse abstürzen. Die Karte wird einfach ausgeblendet und die Leute zahlen anders. Ich will nicht wegen eines Gateway-Ausfalls einen ganzen Verkauf verlieren.

Mark (Auftraggeber)

Letztlich will ich es bis zum fünfzehnten Juli live haben, wegen der Sommerkampagne. Auf Staging soll es bis Ende Juni laufen, damit Lucy genug Zeit hat, es ordentlich durchzuklicken.

Voxibly ausprobieren