Abonnements

Mit dem Shop können Sie ein Abonnement-System für Frontend-Nutzer mit Stripe anbieten. Dafür musst du den Stripe Checkout konfigurieren einrichten.

Abonnements Konfigurieren

1. Loggen Sie sich auf dashboard.stripe.com ein und wechseln Sie zum Abschnitt Products. Hier müssen Sie für jedes Abonnement, das Sie anbieten, ein Produkt erstellen - zum Beispiel Basic-Plan und Premium-Plan. Produkte müssen separat in der Sandbox und im Live-Modus erstellt werden, wobei man Produkte aus der Sandbox in den Live-Modus kopieren kann. Diese Produkte benötigen die folgenden Daten:
   • Name: Produktnamen sind für Kunden an der Kasse, auf Quittungen, Rechnungen und im Kundenportal sichtbar.
   • Beschreibung: Produktbeschreibungen erscheinen an der Kasse und im Kundenportal.
   • Fügen Sie einen Preis ein und stellen Sie sicher, dass wiederkehrende Zahlung ausgewählt ist.
   • Fügen Sie dem Produkt ein Meta-Tag mit dem Schlüssel category hinzu. Produkte können nach dem Wert dieses Tags im Plugin SubscriptionTable gefiltert werden (siehe Abschnitt "Tabelle der Abonnementprodukte anzeigen").
   • Fügen Sie dem Produkt ein Meta-Tag mit dem Schlüssel usergroups hinzu. Setzen Sie den Wert dieses Tags auf eine durch Kommata getrennte Liste von Frontends-Nutzergruppen. Diese Nutzergruppen werden automatisch zu den Frontendnutzern hinzugefügt, die ein Abonnement erwerben, das dieses Produkt enthält. Wenn ein Abonnement endet, werden diese Benutzergruppen automatisch aus dem Frontendbenutzer-Datensatz entfernt. Die Frontend-Benutzer und Frontend-Benutzergruppen müssen im gleichen Datensatz-Container sein.
   • Füge einen optionalen Meta-Tag mit dem Schlüssel trial_period_days hinzu, der die Anzahl der Tage für die Testphase des ersten Abonnements eines Benutzers definiert. Dies wird nur verwendet, wenn das Feld e_users.tx_shop_stripe_trial_period_end leer ist.
   • Konfigurieren Sie Webhooks (siehe Abschnitt "Konfiguration der Stripe-Webhooks").

Attention:

Bei der Verwendung von Stripe-Kunden benötigt der Frontend-Benutzer in seinem Benutzerdatensatz den kurzen Iso-Code seines Landes (z.B.: DE)!

Konfiguration der Stripe-Webhooks

Ein Webhook für den Empfang von Stripe-Events ist grundsätzlich erforderlich, um die mit einem Stripe-Produkt verknüpften Benutzergruppen automatisch zuzuweisen oder zu entfernen und beispielsweise Abowechsel korrekt abzuwickeln.

Um die Konfiguration zu vereinfachen, kann eine Kurz-URL für die Seite mit einem SubscriptionTable- oder Subscriptions-Plugin eingerichtet werden.

  ShopSubscriptionsPlugin:
    type: Extbase
    limitToPages:
      - {page uid with the Subscriptions plugin}
    extension: ShopPro
    plugin: Subscriptions
    routes:
      - routePath: '/stripe-subscription-callback'
        _controller: 'Subscription::stripeSubscriptionCallback'
    defaultController: 'Subscription::list'

or

  ShopSubscriptionsPlugin:
    type: Extbase
    limitToPages:
      - {page uid with the SubscriptionTable plugin}
    extension: ShopPro
    plugin: SubscriptionTable
    routes:
      - routePath: '/stripe-subscription-callback'
        _controller: 'Subscription::stripeSubscriptionCallback'
    defaultController: 'Subscription::list'

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 checkout.session.completed, customer.subscription.created, customer.subscription.updated und customer.subscription.deleted.
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 subscriptionEndpointSecretTypoScript Konstante ein.

Lokale Verwendung des Stripe-Webhooks

1. Stripe CLI installieren Lade das offizielle Debian-Package herunter und installiere es:

   # Beispiel für Debian/Ubuntu
   wget https://stripe.jfrog.io/artifactory/deb-local/pool/main/s/stripe-cli/stripe-cli_<version>_amd64.deb
   sudo dpkg -i stripe-cli_<version>_amd64.deb

   Ersetze <version> durch die aktuellste Version, die Du auf der Stripe-Repository-Seite findest.

2. Mit Deinem Stripe-Account verbinden

   stripe login

   – Dadurch öffnet sich ein Browserfenster, in dem Du Dich bei Stripe anmeldest und den Zugriff verifizierst.

3. Webhooks weiterleiten Wechsle zurück in Dein Terminal und starte den Listener mit Weiterleitung auf Deine DDEV-URL:

   stripe listen \
     --forward-to https://typo3-12-13.shop13.ddev.site/subscription/your-subscriptions/stripe-subscription-callback

   – Der Listener hängt sich an Stripe-Events (z. B. invoice.paid, customer.subscription.updated) und schickt sie an Deinen lokalen Callback-Endpoint. Achte dabei darauf, dass die lokale Nutzung einen eigenen Webhook-Secret bekommt, welcher beim Start auf der CLI ausgegeben wird: Your webhook signing secret is whsec_03b75a…

4. Callback-Endpoint in TYPO3 prüfen – Stelle sicher, dass Dein TYPO3-Projekt unter der DDEV-URL erreichbar ist und der Callback-Controller die übertragenen JSON-Daten korrekt verarbeitet. – Falls nötig, aktiviere in DDEV HTTPS (standardmäßig an) und passe ggf. config.yaml an.

PSR-14 Events

Wenn

• der Webhook korrekt eingerichtet ist
• trifft eines der unterstützten Ereignisse beim Webhook ein
  • https://stripe.com/docs/api/events/types#event_types-customer.subscription.created
  • https://stripe.com/docs/api/events/types#event_types-customer.subscription.updated
  • https://stripe.com/docs/api/events/types#event_types-customer.subscription.deleted
• es existiert ein Benutzer in der Datenbank mit der entsprechenden Stripe-Kunden-ID

wird ein PSR-14-Event ausgelöst.

Fügen Sie Folgendes zu Configuration/Services.yaml hinzu, um auf die Events zu reagieren:

services:
  Vendor\MyExtension\EventListener\SubscriptionCreatedEventListener:
    tags:
      - name: event.listener
        identifier: 'SubscriptionCreatedEventListener'
        event: CodingMs\ShopPro\Event\Stripe\Subscriptions\StripeSubscriptionCreatedEvent
  Vendor\MyExtension\EventListener\SubscriptionUpdatedEventListener:
    tags:
      - name: event.listener
        identifier: 'SubscriptionUpdatedEventListener'
        event: CodingMs\ShopPro\Event\Stripe\Subscriptions\StripeSubscriptionUpdatedEvent
  Vendor\MyExtension\EventListener\SubscriptionDeletedEventListener:
    tags:
      - name: event.listener
        identifier: 'SubscriptionDeletedEventListener'
        event: CodingMs\ShopPro\Event\Stripe\Subscriptions\StripeSubscriptionDeletedEvent

Dieses Ereignis enthält das Stripe-Subscription-Objekt und den zugehörigen Frontend-Benutzer.

Weitere Informationen zur Registrierung eines Event-Listeners finden Sie hier: https://docs.typo3.org/m/typo3/reference-coreapi/main/en-us/ApiOverview/Events/EventDispatcher/Index.html#registering-the-event-listener

Tabelle der Abonnementprodukte anzeigen

• verwenden Sie das Plugin SubscriptionTable
• fügen Sie bei der Produkterstellung dem Produkt ein Meta-Tag mit dem Schlüssel category hinzu und setzen Sie einen benutzerdefinierten Bezeichner (z.B.: subscription). Dies ermöglicht Ihnen, bestimmte Produkte in Abonnement-Tabellen anzuzeigen.

Liste der Abonnements anzeigen

• Verwenden Sie das Plugin Subscriptions

Der Nutzer hat die Möglichkeit, die Liste seiner aktiven und bereits abgelaufenen Abonnements einzusehen und die Abonnements sofort oder zum Ende der Laufzeit zu kündigen. Für jedes Abonnement hat der Benutzer die Möglichkeit, die Liste der Rechnungen einzusehen und diese herunterzuladen.

Nebenbemerkung: Benutzer-Synchronisation

Stripe benötigt einen Stripe-Kundendatensatz für jeden unserer Frontend-Benutzer. Um diese Anforderung zu erfüllen, hat jeder Frontend-Benutzer ein Feld Stripe-Customer ID. Wenn ein Frontend-Benutzer eingeloggt ist und die Stripe-Customer ID leer ist, wird ein Versuch unternommen, einen neuen Stripe-Kunden anzulegen. Die neue Stipe-Kunden-ID wird dem Benutzerdatensatz zugeordnet. Wenn die Adressdaten des Frontend-Benutzers geändert werden, werden die geänderten Daten automatisch mit Stripe synchronisiert.

Es ist sehr wichtig, den Stripe-Kunden-Datensatz auf dem neuesten Stand zu halten, wenn Tools oder Skripte von Drittanbietern zum Ändern von Benutzerdaten im Frontend verwendet werden. Falls erforderlich, kann die Benutzersynchronisation manuell aufgerufen werden. Ein Beispiel finden Sie in EXT:shop_pro/Classes/EventListener/AfterProfileUpdateEventListener.php

public function __invoke(AfterProfileUpdatedEvent $event): void
{
    $frontendUserRepository = GeneralUtility::makeInstance(FrontendUserRepository::class);
    $frontendUser = $frontendUserRepository->findOneByUid($event->getFrontendUser()->getUid() ?? 0);
    if(!isset($frontendUser)) {
        return;
    }
    $routing = $GLOBALS['TYPO3_REQUEST']->getAttribute('routing');
    $pageId = $routing->getPageId();
    $subscriptionServiceSettings = TypoScriptService::getTypoScript(
        $pageId
    )['plugin']['tx_shop']['settings']['basketOrder']['orderOptions']['stripe'];
    $subscriptionService = GeneralUtility::makeInstance(SubscriptionService::class, $subscriptionServiceSettings);
    $subscriptionService->updateStripeCustomer($frontendUser);
}

Hinweis:

Alle Stripe-Elemente werden in der Sprache verwendet, die der Benutzer gerade auf der Website verwendet. Diese wird aus der Site-Configuration ausgelesen.