Headless-Storefronts (GraphQL)
Nutzen Sie Stripe Payment aus einer App oder einem eigenen Frontend heraus.
Hintergrund
Lesen Sie dieses Kapitel, wenn Ihr Shop nicht nur über das Standard-Theme von OXID genutzt wird, sondern auch über ein separates Web-Frontend, eine mobile App, ein Kiosk-Terminal oder eine Partner-Website. Ein solches Frontend nimmt Stripe-Zahlungen über die GraphQL-API des Shops entgegen, während Ihr Shop die volle Kontrolle über Bestellungen, das Stripe-Konto und das Geld behält.
Jede Bestellung aus einem Headless-Frontend ist eine normale Shop-Bestellung mit der Stripe-Zahlungsart: dieselbe Bestellverwaltung, dieselbe Erfassung und Rückerstattung, dieselbe Webhook-Verarbeitung wie bei Bestellungen aus dem OXID-Theme.
Das Frontend erhält niemals ein Stripe-Geheimnis. Es erhält nur den veröffentlichbaren Schlüssel (Publishable Key), und zwar nur über einen verschlüsselten Austausch, der an die Sitzung des Kunden gebunden ist. Sie müssen nichts in das Frontend kopieren.
Nach der Zahlung können Kunden nur auf Seiten zurückgeleitet werden, deren Origin Sie freigegeben haben.
Die Bestellung wird durch den Webhook von Stripe abgeschlossen. Ein Kunde, der die App direkt nach dem Bezahlen schließt, erhält seine Bestellung trotzdem.
Note
Modulversionen: Der Headless-Checkout setzt Stripe Payment ab Version 3.4 und OXID Payment Base ab Version 1.3 voraus.
Der Checkout für Gäste ohne Kundenkonto setzt Stripe Payment ab Version 3.5 und OXID Payment Base ab Version 1.5 voraus.
Was Ihre Kunden sehen
Das Frontend wählt die Darstellung für jeden Checkout:
Modus |
Was der Kunde sieht |
Voraussetzungen |
|---|---|---|
Eingebettet |
Das Stripe-Bezahlformular innerhalb der Checkout-Seite des Frontends (Stripe Embedded Checkout) |
Der veröffentlichbare Schlüssel – wird vom Shop automatisch geliefert |
Gehostet |
Eine Weiterleitung auf die Checkout-Seite von Stripe, danach zurück zum Frontend |
Keine |
Ist die automatische Schlüsselübergabe nicht verfügbar, weicht ein gut gebautes Frontend von selbst auf die gehostete Seite aus.
Note
Die Einstellung Iframe statt Checkout-Schaltfläche verwenden (siehe Checkout-Darstellung wählen) gilt nur für das OXID-Theme. In einem Headless-Frontend entscheidet das Frontend.
Shop für ein Headless-Frontend einrichten
Voraussetzungen
Stripe Payment ist wie unter Konfiguration beschrieben installiert und konfiguriert: Stripe-Konto verbunden, Modus (Test/Live), Erfassungsmodus.
Der veröffentlichbare Schlüssel des verwendeten Modus ist eingetragen. Diesen Schlüssel erhält das Frontend.
Der Webhook ist angelegt und über HTTPS erreichbar (siehe Webhook anlegen).
Vorgehen
Installieren und aktivieren Sie die OXID-GraphQL-Module oxid-esales/graphql-base und oxid-esales/graphql-storefront.
Ohne diese Module funktioniert Stripe Payment weiterhin im OXID-Theme, es gibt aber keine API für ein Frontend.
Leeren Sie den GraphQL-Schema-Cache. Führen Sie auf dem Server im Verzeichnis Ihres OXID eShops folgenden Befehl aus:
vendor/bin/oe-console oe:graphql:cache-clearIm OXID Docker SDK lautet der Befehl bin/oe-console.
Important
Wiederholen Sie diesen Schritt nach jeder Aktivierung oder Aktualisierung von Stripe Payment, OXID Payment Base oder eines anderen Moduls, das API-Aufrufe hinzufügt. Das API-Schema wird auf der Festplatte zwischengespeichert, und der Shop leert diesen Cache nie selbst. Ohne diesen Schritt antwortet ein aktualisierter Shop weiterhin mit der alten API.
Geben Sie die Origins des Frontends frei:
Wählen Sie .
Tragen Sie unter Headless-Checkout (GraphQL, Apps) im Feld Erlaubte Rücksprung-Origins für Headless-Clients jeden Origin ein, unter dem Ihre Frontends laufen, getrennt durch Komma oder Zeilenumbruch.
Beispiel
https://shop.example.com, https://app.example.com, http://localhost:5173
Ein Origin besteht aus Schema, Host und Port:
https://app.example.com:8443undhttps://app.example.comsind zwei getrennte Einträge. Die URL Ihres Shops ist immer erlaubt. Bleibt das Feld leer, ist nur der Shop selbst erlaubt.Speichern Sie Ihre Eingaben.
Läuft das Frontend auf einer anderen Domain als der Shop, erlauben Sie ihm den Zugriff auf die API (CORS für
/graphql/). Das ist eine Einstellung des Webservers; wenden Sie sich an Ihren Hosting-Partner.Geben Sie dem Frontend-Team die URL Ihres Shops – und nichts weiter. Die Schlüssel liefert der Shop selbst; der geheime Stripe-Schlüssel, das OAuth-Token und das Webhook-Geheimnis verlassen die Moduleinstellungen nie.
Testen Sie zuerst im Stripe-Testmodus: Bezahlen Sie im Frontend mit einer Testkarte und prüfen Sie dann, dass
die Bestellung unter mit der Stripe-Zahlungsart erscheint,
das Stripe-Dashboard die Testzahlung anzeigt,
der Webhook zugestellt wurde.
Schalten Sie das Modul anschließend in den Live-Modus.
Resultat
Das Frontend kann Stripe-Zahlungen über die GraphQL-API starten. Die Bestellungen werden in Ihrem Shop wie jede andere Stripe-Bestellung verarbeitet.
Zuständigkeiten: Shop und Frontend
Im Shop (Sie) |
Im Frontend (die Entwickler) |
|---|---|
Stripe-Konto, geheimer Schlüssel, Webhook-Geheimnis, Erfassungsmodus |
Welche Darstellung angeboten wird (eingebettet oder gehostet) |
Auf welche Origins Kunden zurückgeleitet werden dürfen |
Das Aussehen der Checkout-Seite |
Die Bestellung, ihre Nummer und ihr Status, Erfassung und Rückerstattung |
Anzeige von Bestellnummer und Status für den Kunden |
Der veröffentlichbare Schlüssel, verschlüsselt pro Sitzung übergeben |
Abruf des Schlüssels, wenn der Zahlungsschritt öffnet |
Die Protokollierungsregeln: keine Provider-Texte, keine vollständigen Rücksprung-URLs und keine Tokens im Shop-Log. Setzen Sie in PHP zend.exception_ignore_args=On (Standard im Produktivbetrieb). |
Protokollierung ohne Query-Strings im eigenen Webserver |
Bestellungen, Erfassung und Rückerstattung
Gegenüber Bestellungen aus dem OXID-Theme ändert sich nichts; siehe Betrieb.
Bei manueller Erfassung wird eine Headless-Bestellung als autorisiert angelegt und ist bezahlt, sobald Sie die Zahlung erfassen.
Abgebrochene oder aufgegebene Zahlungsversuche hinterlassen keine abgeschlossene Bestellung: Das Frontend zieht sie zurück, und die beim Start des Checkouts angelegte Bestellung wird storniert.
Checkout für Gäste
Note
Verfügbar ab Stripe Payment 3.5 und OXID Payment Base 1.5.
Auch Kunden ohne Kundenkonto können bezahlen. Das Frontend sendet ihre E-Mail-Adresse und Rechnungsadresse – und optional eine Lieferadresse – zusammen mit dem Start des Checkouts. Der Shop legt für diese E-Mail-Adresse ein Gastkonto ohne Passwort an und verwendet es bei der nächsten Gastbestellung mit derselben Adresse wieder.
Gehört die E-Mail-Adresse zu einem registrierten Kundenkonto, wird der Checkout abgelehnt und das Konto nicht verändert. Das Frontend fordert den Kunden auf, sich anzumelden.
Bekannte Einschränkung: Die Bestellung wird derzeit an die Rechnungsadresse geliefert, auch wenn der Gast eine abweichende Lieferadresse angegeben hat.
Fehlerbehebung
Symptom |
Ursache |
Lösung |
|---|---|---|
Das Frontend meldet return_url_rejected / origin_not_allowed. |
Der Origin des Frontends ist nicht freigegeben. |
Tragen Sie ihn unter Erlaubte Rücksprung-Origins für Headless-Clients ein und leeren Sie den GraphQL-Schema-Cache. |
Das Frontend zeigt die gehostete Stripe-Seite, obwohl das eingebettete Formular erwartet wurde. |
Der veröffentlichbare Schlüssel des aktuellen Modus ist leer oder kein pk_…-Schlüssel – oder OXID Payment Base ist zu alt, um den Schlüssel zu liefern. |
Tragen Sie den veröffentlichbaren Schlüssel ein; aktualisieren Sie OXID Payment Base und aktivieren Sie die Module erneut. |
Die Bestellung bleibt im Frontend auf „ausstehend“. |
Der Webhook hat den Shop noch nicht erreicht oder ist nicht registriert. |
Legen Sie den Webhook an; prüfen Sie die Zustellfehler unter . Der Shop muss über HTTPS erreichbar sein. |
Cannot query field „stripeCheckoutStart“ |
Die GraphQL-Module sind nicht installiert oder nicht aktiv, oder Stripe Payment wurde vor ihnen aktiviert. |
Installieren und aktivieren Sie graphql-base und graphql-storefront, aktivieren Sie dann Stripe Payment erneut. |
Cannot query field „…“ für einen dokumentierten Aufruf, obwohl das Modul aktiv ist |
Der GraphQL-Schema-Cache enthält noch das Schema von vor der Aktivierung oder Aktualisierung. |
Führen Sie vendor/bin/oe-console oe:graphql:cache-clear aus und wiederholen Sie den Aufruf. |
Ein Gast erhält account_exists. |
Die E-Mail-Adresse gehört zu einem registrierten Kundenkonto. |
Der Kunde meldet sich an. Am Konto wurde nichts verändert. |
Ein Gast erhält guest_details_required. |
Das Frontend hat keine oder unvollständige Gastdaten gesendet (E-Mail-Adresse, Rechnungsadresse). |
Korrigieren Sie das Formular des Frontends; die Fehlermeldung nennt das fehlende Feld. |
Einschränkungen
Unterstützt werden nur die gehostete Seite von Stripe und Stripe Embedded Checkout, keine eigenen Stripe Elements.
Für Entwickler: Die API (Mutations, Aufrufreihenfolge, Fehlercodes) ist in der Entwickler-Dokumentation von OXID Payment Base beschrieben, Kapitel Headless Checkout (GraphQL).