Stripe

Stripe im Backend

Stripe verbindet den Shop mit Stripe Checkout, speichert API-Schlüssel pro Shop und verarbeitet erfolgreiche oder fehlgeschlagene Stripe-Zahlungen über signierte Webhooks.

Inhaltsverzeichnis

Einordnung und Voraussetzungen

Stripe ist eine Anbieter-Unterseite der Zahlungsarten. Allgemeine Regeln wie Aktivstatus, Reihenfolge, Kosten, Wertgrenzen, Kundengruppen, Versandarten und Versandzonen bleiben auf der Hauptseite der Zahlungsarten gepflegt. Diese Seite beschreibt die Stripe-spezifische Konfiguration.

  • Shop-Bezug: Die Konfiguration wird je Multishop im Bereich stripe gespeichert.
  • Automatische Initialisierung: Fehlende Variablen werden je Shop angelegt. Dazu gehören public_key, secret_key, payment_method_types, order_status_ok, order_status_error, status_ok_createBill, status_ok_sendBill und endpoint_secret.
  • Checkout-Verfügbarkeit: Stripe kann im Checkout nur erscheinen, wenn die allgemeine Zahlungsart für den aktuellen Warenkorb- und Versandkontext erlaubt ist.
  • Keine eigene Liste: Diese Seite hat keine Suchmaske, keine Datentabelle und keine Optionsspalte. Die Verwaltung erfolgt über ein Formular.

Zugangsdaten und Webhook-Secret

FeldZweck und Wirkung
public_key Public API KeyÖffentlicher Stripe-Schlüssel der verwendeten Stripe-Umgebung.
secret_key Secret API KeyGeheimer Stripe-Schlüssel. Das Modul nutzt diesen Wert zum Erstellen von Checkout-Sessions und Webhook-Endpunkten.
endpoint_secret Webhook Secret KeySignatur-Secret für eingehende Stripe-Webhooks. Beim Speichern versucht das Modul automatisch einen Webhook-Endpunkt zu erstellen, wenn dieses Feld leer ist.
Wichtig: Test- und Live-Schlüssel müssen zur gleichen Stripe-Umgebung gehören wie das Webhook-Secret. Nach einem Schlüsselwechsel sollte auch das Webhook-Secret geprüft oder neu erzeugt werden.

Zahlungsmethoden

Das Feld payment_method_types steuert, ob der Shop Stripe konkrete Zahlungsmethoden vorgibt.

  • Standardwert: card.
  • Mehrere Methoden: Werte werden kommagetrennt eingetragen und beim Checkout an Stripe übergeben.
  • Leeres Feld: Das Modul übergibt keine expliziten Methoden. Dann greift die Steuerung aus der Stripe-Konfiguration.

Beim Erstellen der Checkout-Session wird payment_method_types nur gesetzt, wenn das Feld nicht leer ist.

Status und Rechnung

FeldZweck
order_status_okBestellstatus nach erfolgreichem Stripe-Webhook. Das Modul setzt diesen Status beim Erfüllen der Bestellung.
order_status_errorBestellstatus bei fehlgeschlagener asynchroner Zahlung.
status_ok_createBillÜbergibt an die Checkout-Rechnungslogik, ob nach erfolgreicher Zahlung eine Rechnung erzeugt wird. Im neuen Backend ist der Schalter ohne aktives FiBu-Modul deaktiviert.
status_ok_sendBillÜbergibt an die Checkout-Rechnungslogik, ob die erzeugte Rechnung versendet wird. Auch dieser Schalter hängt im neuen Backend vom FiBu-Modul ab.

Speichern und automatische Webhook-Erstellung

Beim Speichern werden die Formularwerte für den ausgewählten Shop übernommen. Wenn endpoint_secret leer ist, speichert das Modul zuerst die übrigen Werte, erstellt danach einen Stripe-Webhook-Endpunkt und schreibt das zurückgelieferte Secret in die Konfiguration.

Der automatisch angelegte Webhook zeigt auf den Stripe-Eingang des Shops und abonniert folgende Events:

  • checkout.session.completed
  • checkout.session.async_payment_succeeded
  • checkout.session.async_payment_failed

Checkout-Ablauf

  1. Im Checkout wird Stripe als Zahlungsart ausgewählt.
  2. Das Modul lädt die Stripe-Konfiguration und setzt den geheimen API-Schlüssel.
  3. Es erstellt eine Stripe-Checkout-Session mit Erfolgs- und Abbruchziel, Kunden-E-Mail, Modus payment, Metadatum order_id, Bestellnummer als client_reference_id und einer Position für den kompletten Bruttobestellwert.
  4. Wenn payment_method_types gefüllt ist, werden die kommagetrennten Zahlungsmethoden an Stripe übergeben.
  5. Die erstellte Checkout-Session wird im Tageslog protokolliert.
  6. Der Browser wird mit HTTP-Status 303 zur Stripe-Zahlungsseite weitergeleitet.

Rückkehr aus Stripe

  • Erfolg: Bei erfolgreicher Rückkehr markiert das Backend die Bestellung als abgeschlossen, aktualisiert Gutscheincodes, leert den Warenkorb, erhöht den Kundschaftsumsatz und versendet bei aktivierter Shop-Einstellung die Bestellbestätigung. Der finale Zahlungsstatus wird zusätzlich über Webhooks verarbeitet.
  • Abbruch: Wenn die Bestellung noch nicht fertig ist, wird diese gelöscht und der Warenkorb erneut angezeigt. Ist die Bestellung bereits fertig, bleiben Bestelldaten erhalten und der Warenkorb wird geleert.
  • Initialer Aufruf: Ohne Erfolg oder Abbruch setzt das Modul die Zahlungsfreigabe für den weiteren Checkout-Ablauf und hält den Warenkorb bis zur Rückmeldung zurück.

Webhook-Verarbeitung

Der öffentliche Stripe-Eingang lädt das Stripe-Modul und ruft die Webhook-Verarbeitung auf. Der Payload wird mit endpoint_secret und dem Stripe-Signaturheader geprüft. Ungültige Payloads oder Signaturen führen zu HTTP 400 und werden protokolliert.

EventBackend-Wirkung
checkout.session.completedOrdnet die Session über metadata.order_id und client_reference_id der Bestellung zu. Nur bei Stripe-Zahlungsstatus paid wird die Bestellung erfüllt.
checkout.session.async_payment_succeededOrdnet die Session der Bestellung zu und erfüllt die Bestellung nach verzögerter erfolgreicher Zahlung.
checkout.session.async_payment_failedOrdnet die Session der Bestellung zu und setzt den Status aus order_status_error.
Unbekanntes EventWird im Stripe-Log als unbekannter Event dokumentiert und mit HTTP 200 bestätigt.

Beim Erfüllen einer Bestellung setzt das Modul order_status_ok, schreibt einen Logeintrag und ruft die Rechnungslogik mit status_ok_createBill und status_ok_sendBill auf.

Logs und Prüfung

Stripe stellt einen Admin-Logviewer für tägliche Logdateien bereit. Die Loganzeige nutzt den Prefix stripe und maskiert Secrets sowie Tokens zusätzlich.

  • Nach Änderung von API-Schlüsseln prüfen, ob das passende endpoint_secret gespeichert ist.
  • Nach Änderung von payment_method_types eine Checkout-Session mit passender Zahlungsart testen.
  • Nach Änderung der Statusfelder eine erfolgreiche Zahlung und einen Fehlerfall prüfen.
  • Bei Rechnungserstellung testen, ob FiBu-Modul, Rechnungserzeugung und Rechnungsversand zusammen aktiv sind.
  • Im Stripe-Logviewer kontrollieren, ob Checkout-Session, Webhook-Eingang und Bestellzuordnung protokolliert werden.

War diese Seite hilfreich?

Hilf uns, das Handbuch weiter zu verbessern. Wenn etwas fehlt oder unverständlich ist, kannst Du direkt einen kurzen Kommentar senden.