Stripe Checkout konfigurieren

Achtung:

Der Stripe Checkout erfordert der die Pro-Version der Shop-Erweiterung!

Hinweis:

Der Stripe Checkout, welcher hier beschrieben wird, bezieht sich auf den Verkauf von normalen Produkte über den Warenkorb. Wenn es um die Bezahlung von Stripe-Abos geht, wechsel zu https://www.coding.ms/de/dokumentation/typo3-shop/warenkorb-checkout/stripe

Vorbereitungen

Um den Stripe Checkout nutzen zu können, müssen folgende Voraussetzungen erfüllt sein:

• Du musst über ein aktiviertes Stripe-Konto verfügen
• Du musst TYPO3 auf composer Basis verwenden

Stripe API-Zugangsdaten

1. Wechsel im Stripe-Login in den Bereich Entwickler -> API-Schlüssel (https://dashboard.stripe.com/apikeys)
2. Erstelle hier neue API-Zugangsdaten
3. Hier bekommst Du nun einen öffentlichen und einen Geheimschlüssel angezeigt
4. Diese Schlüssel müssen via TypoScript-Konstanten im TYPO3 hinterlegt werden
5. Erstellen Sie ein Endpoint-Secret, um Stripe-Events empfangen zu können (https://dashboard.stripe.com/webhooks/create) (siehe Kapitel "Events" für weitere Informationen)
6. Kopieren Sie das Endpoint Secret in die singlePaymentIntentSucceededEndpointSecretTypoScript Konstante

Events

Payment Intent Succeeded Event

Sie müssen einen Event-Listener für das "payment_intent.succeeded" Event konfigurieren, damit das Stripe Checkout weiß, wenn eine Zahlung über Stripe eingegangen ist. Die Einrichtung erfolgt in 2 Schritten.

1. Einrichtung der Webhook-Seite
2. Konfiguration des Webhooks im Stripe Dashboard

Setup der Webhook-Seite

Die Webhook-Seite ist eine normale Seite, die wir definieren und die die stripeCallbackAction im BackendOrderController aufrufen soll.

Du erstellst dafür also eine normale Seite, welche im Menü nicht sichtbar ist, aus der sitemap.xml ausgeschlossen wird und auf noindex/nofollow steht. Die Seite bekommt den Titel Stripe-Callback und den Slug s damit die URL schön kurz wird. Bei der Erstellung hat unsere Seite die uid 123 bekommen.

🌎 Website root
├─ ...
└─ 📄 Stripe-Callback [123]

Auf dieser Seite muss nun ein Plugin vom Typ Shop Checkout erstellt werden. Damit der Callback-Aufruf von Stripe jetzt die richtige Controller-Action ausführt, ist es zwingend erforderlich, das die entsprechende Route in der Site-Configuration eingerichtet wird. Diese sieht in unserem Fall so aus:

  ShopCheckoutPlugin:
    type: Extbase
    limitToPages:
      - {123}
    extension: Shop
    plugin: BasketOrder
    routes:
      - routePath: '/stripe-callback'
        _controller: 'BasketOrder::stripeCallback'

Wichtig ist, dass die richtige Seiten-Uid eingetragen wird, in unserem Fall 123. Der eingetragenen routePath erweitert unseren Slug der Seite. Er sorgt dafür, dass unser Aufruf die Controller-Action BasketOrder::stripeCallback aufruft.

Das heißt, der URL welche in den Webhook bei Stripe eingetragen werden muss, sieht wie folgt aus: https://www.domain.tld/s/stripe-callback.

Leere nun den System-Cache und rufe die URL einmal im Browser auf. Wenn einfach nur eine weiße Seite mit einem 403 darauf erscheint, sollte alles richtig eingerichtet sein.

Achtung:

Deine Seite darf nicht mit einem Passwort wie bspw. .htaccess geschützt sein, da sonst der Stripe-Callback nicht durch kommt!

Konfiguration des Webhooks im Stripe Dashboard

1. Gehen Sie auf die Seite https://dashboard.stripe.com/webhooks und klicken Sie auf Endpunkt hinzufügen.
2. Geben Sie die URL der Seite ein, die im Schritt "Einrichten der Webhook-Seite" eingerichtet wurde.
3. Wählen Sie "Select Events" und wählen Sie payment_intent.succeeded.
4. klicken Sie auf "Endpunkt hinzufügen".
5. Klicken Sie auf den neu erstellten Webhook-Eintrag und kopieren Sie das Endpoint Secret.
6. Fügen Sie das Endpoint Secret in die singlePaymentIntentSucceededEndpointSecretTypoScript Konstante ein.

Zum Testen des Webhooks in einer lokalen Entwicklungsumgebung kann das Stripe cli Tool verwendet werden. Mehr Informationen dazu finden Sie hier: https://stripe.com/docs/webhooks/quickstart#download

Aktionen nach erfolgreicher Bezahlung

Wenn Du nach der erfolgreichen Bezahlung weitere Aktionen durchführen möchtest, kannst Du dazu den StripePaid Event Listener nutzen.

1. Dazu muss ein Event Listener erstellt werden:

   <?php
   namespace YourVendor\YourExtension\EventListener;
   use CodingMs\ShopPro\Event\BasketOrder\StripePaidEvent;
   class DoSomeThingEventListener
   {
       public function __invoke(StripePaidEvent $event): void
       {
           /* Do something */
       }
   }

2. Dieser Event Listener muss anschließend in der Configuration/Services.yaml registriert werden:

   services:
       YourVendor\YourExtension\EventListener\DoSomeThingEventListener:
           tags:
               - name: event.listener
                 identifier: 'myListener'
                 event: CodingMs\ShopPro\Event\BasketOrder\StripePaidEvent

Testing

Siehe: https://stripe.com/docs/testing

Test Credit Card

Um den Kartenzahlungsfluss aus der Sicht des Endbenutzers zu simulieren/testen, verwendest Du die folgenden Kartendetails im geladenen Klarna-Widget:

Credit card number: 4242 4242 4242 4242 CVV: 123 Exp: 12/25 (Oder ein anderes gültiges Datum in der Zukunft)

Fehlerbehandlung und Meldungen

Der Stripe-Checkout verwendet die JavaScript-Methode FlashMessage.push() zum Pushen von Nachrichten. Für diesen Dienst musst Du einen div-Container als Wrapper für die Nachrichten definieren, zum Beispiel <div id="shop-flash-messages"></div>.

Der Aufruf des Webhooks endet mit einem 404-Fehler

Der Aufruf des Webhooks ergibt ein:

Page Not Found
Reason: Request parameters could not be validated (&cHash empty)

Lösung 1.:

Öffne das Installtool und deaktiviere die Einstellung pageNotFoundOnCHashError: [FE][pageNotFoundOnCHashError] = false

Lösung 2.

Entferne die Parameter des Requests aus der cHash Berechnung (LocalConfigration/settings.php):

'FE' => [
    'cacheHash' => [
        'enforceValidation' => true,
        'excludedParameters' => [
            'payment_intent',
            'payment_intent_client_secret',
            'redirect_status',
        ],
    ],
],