Contao mit Digistore24 verbinden

Contao-Digistore-Connector

Diese Erweiterung verbindet den Zahlungsanbieter Digistore mit Contao. Du kannst damit digitale Produkte, Mitgliederbereiche und Abo-Produkte automatisiert mit Contao anbieten. Die komplette Zahlung läuft dabei über Digistore.

Auszug Funktionsumfang

  • Verknüpfung der Digistore-Produkte mit Contao
  • Funktioniert bei Einzelkäufen und Abo-Produkten
  • Bei Bestellungen wird automatisch ein Benutzer angelegt und ein Passwort generiert
  • Contao-Berechtigungsgruppen zuweisen und entfernen
  • Individuelle Aktionen auf die unterschiedlichen IPN-Events von Digistore konfigurierbar
  • Sammeln der Bestelldaten in einer Übersicht
  • Versand von individuellen E-Mails bei unterschiedlichen IPN-Events über das Notification-Center
  • Kündigungsfunktion bei Abos

Weitere Funktionen sind für zukünftige Versionen geplant.

Voraussetzungen

So setzt du die Erweiterung ein

1. Installation

Für den Einsatz der Erweiterung ist eine Lizenz nötig, welche du hier bestellen kannst. Du erhältst von uns dann einen speziellen Access-Token zur Installation der Erweiterung.

1.1 composer.json anpassen

Die Extension muss manuell der composer.json hinzugefügt werden. Die Erweiterung kann derzeit NICHT über den Contao Manager und den Extension-Katalog gefunden werden.

Zunächst muss die composer.json per Editor geöffnet werden und folgende Bereiche ergänzt werden:

  • require
  • repositories

Für Contao 4.13 & Notification Center 1.x

"require": {
    "contaoacademy/contao-digistore24": "^1.2"
}

Für Contao 4.13 | 5.3 & Notification Center 2.x

"require": {
    "contaoacademy/contao-digistore24": "^2.0"
}

Eintrag unabhängig von der Contao Version

"repositories": {
    "contaoacademy/contao-digistore24": {
        "type": "composer",
        "url": "https://token:DEIN-TOKEN-ACCESSKEY@packdis.inspiredminds.at/r"
    }
}

1.2 Composer update durchführen

Nachdem du die composer.json angepasst hast, musst du nun über die Konsole ein composer update durchführen bzw. über den
Contao Manager Pakete aktualisieren ausführen.

1.3 Datenbank aktualisieren

Zum Schluss rufst du das Installtool bzw. den Contao Manager im Browser auf und führst die nötigen Datenbankaktualisierungen durch.

2. Basiskonfiguration Digistore-Anbindung

2.1 IPN-Passwort festlegen und bei Contao hinterlegen

Generiere ein sicheres Passwort und hinterlege dies in der /config/config.yml. Falls die Datei nicht vorhanden ist, muss diese neu angelegt werden.

Damit eine neue Konfiguration wirksam werden kann, musst du nach Veränderungen an den Konfigurationsdateien den Production-Cache über den Contao Manager (alternativ über die Kommandozeile) löschen.

Hinweis: Bitte verwende derzeit im Passwort nur Zeichen von Aa bis Zz und Zahlen von 0 bis 9. Mit Sonderzeichen kommt es aktuell zu Problemen.

# config/config.yml
contao_digistore24:
    ipn_passphrase: DEIN-IPN-PASSWORD

2.2 Neue IPN-Integration bei Digistore einrichten

  1. Bei Digistore24 einloggen
  2. Menüpunkt: Einstellungen » Anbindungen (IPN)
  3. Blauer Button: Neue Anbindung hinzufügen
  4. Für Profis » Generisch
  5. Einstellungen
    • Name: individuell
    • Produkte: Alle oder individuell
    • Für Addons: Ja (nach individuellem Bedarf)
    • Sprachen: Alle oder individuell
    • Benachrichtungen bei: Kunden-Bestellungen
    • Bestell-Ereignisse: Zahlung (Weitere nach Bedarf und Konfiguration in Contao)
    • Upsells: werden derzeit nicht unterstützt
    • Call bei IPN-Fehlern wiederholen: Ja
    • IPN URL: https://<YOUR-DOMAIN>/_digistore24/ipn
    • Request-Methode: POST
    • IPN-Kennwort: wie bei Contao in config.yml
    • Erfolgserkennung: Standard
    • IPN-Timing: Vor dem Weiterleiten auf die Dankeseite
    • Aktiv: ja
    • IPN-Benachrichtigung wird versendet: … in jedem Fall.
    • E-Mail-Adresse für Fehler: individuell
  6. «Speichern» und anschließend «Verbindung testen»

3 Notification Center einrichten

Zum Versand der Mails wird das Notification Center benötigt.

3.1 Grundkonfiguration E-Mail-Gateway

Damit das Notification Center Mails versenden kann, muss im 1. Schritt ein «Standard E-Mail-Gateway» angelegt werden.

Sieh dir dazu folgendes Video auf YouTube an:
Contao Notification Center Anleitung

3.2 Benachrichtigungen anlegen

Damit die Zugangsdaten per E-Mail versendet werden können, sollten mindestens die folgenden 2 Benachrichtigungstypen konfiguriert werden.

  • Digistore24: IPN-Event: neues Mitglied
  • Digistore24: IPN-Event: bestehendes Mitglied

Wie du grundsätzlich Benachrichtigung im Notification Center einstellen kannst, siehst du in diesem Video.

Spezielles Feld für das Passwort
Bei neuen Mitgliedern wird automatisch ein Passwort generiert. Dieses steht nur einmalig bei neuen Bestellungen zur Verfügung und wird über den Simple-Token ##generated_password## abgefragt.

Zugriff auf IPN-Daten per Simple-Token
Um die Mails zu individualisieren, können Simple-Token verwendet werden. Neben den Contao-Standard-Token kann auch auf die IPN-Felder zugegriffen werden. Diese IPN-Felder müssen allerdings zu diesem Zeitpunkt in der IPN-Nachricht enthalten sein.

Beispiel: ##ipn_email##

Anbei noch ein paar Screenshots.

4 Produkte konfigurieren

Damit die Bestellungen von Digistore in Contao übertragen werden können, muss im Backend eine entsprechende Konfiguration je Produkt angelegt werden.

4.1 Digistore Produkt zuordnen

  1. Contao Backend anmelden
  2. Menüpunkt: DIGISTORE24 » Produkte
  3. Neues Produkt anlegen mit einem Klick auf «Neu»
    • Produkt-ID: Produkt-ID bei Digistore24
    • Produktname: individuell nur intern für Contao
    • Produkt veröffentlichen: aktiv
  4. «Speichern und schließen»

4.2 IPN-Events pro Produkt festlegen

Digistore sendet für unterschiedliche Ereignisse (sie Konfiguration IPN-Anbindung) unterschiedliche Events. Auf diese Events kann innerhalb von Contao reagiert werden.

Als Mindestkonfiguration sollte das Event on_payment konfiguriert werden. Weitere Events nach Bedarf ergänzen.

Beispiel «on_payment» Event
  1. Menüpunkt: DIGISTORE24 » Produkte » Stiftsymbol
  2. Neues Event anlegen mit einem Klick auf «Neu»
    • IPN-Event: on_payment
    • Titel: individuell nur intern für Contao
    • Neues Mitglied anlegen: aktiv
      • Mitgliedergruppen: zuordnen
      • Login erlauben: aktiv
      • Benachrichtigung: Neue Bestellung - Zugangsdaten senden
    • Bestehendes Mitglied ändern: aktiv
      • Mitgliedergruppen hinzufügen: zuordnen
      • Login erlauben: Erlauben
      • Benachrichtigung: Neue Bestellung - Zugangsdaten bereits vorhanden
    • Weitere Benachrichtigung: nein
    • Aktiviert: ja
  3. «Speichern und schließen»

5 Kündigung von Abos einrichten

Damit bei Abo-Produkten die Zahlung vom Kunden selbst gestoppt werden kann, bietet der Digistore-Connector eine API-Anbindung an.

5.1 Kontozugriff bei Digistore einrichten

  1. Login bei Digistore
  2. Menüpunkt: Einstellungen » Kontozugriff » API-Schlüssel
  3. Neuer API-Schlüssel
    • Name der Anwendung: beliebig (z.B. Contao-Website)
    • API-Rechte: Vollzugriff
    • Aktiv: Ja
  4. «Speichern»
  5. Generierten API-Key in Zwischenablage kopieren.

5.2 Ein neues Gateway für Digistore anlegen

  1. Contao Backend
  2. Menüpunkt: Notification Center » Gateways
  3. Neues Gateway
    • Titel: beliebig (z.B. DigistoreAPI)
    • Typ: Digistore24 API
    • Digistore24 API Schlüssel: dein unter 5.1 erstellter API-Key
  4. «Speichern und schließen»

5.3 Neue Benachrichtigung & Nachricht anlegen

5.3.1 Benachrichtigung

  1. Menüpunkt: Notification Center » Benachrichtigungen
  2. Neue Benachrichtigung
    • Titel: beliebig (z.B. Kündigung)
    • Benachrichtigungstyp: Formularübertragung
  3. «Speichern und schließen»

5.3.2 Nachricht anlegen

  1. Neue Nachricht
    • Titel: beliebig (z.B. Kündigung per API an Digistore)
    • Gateway: DigistoreAPI
    • Endpunkt: stopRebilling
    • Nachricht veröffentlichen: Ja
  2. «Speichern und schließen»

Optional kann eine weitere Nachricht vom Typ E-Mail hinzugefügt werden um z. B. auch eine Nachricht an den Admin zu senden.

5.4 Neue Formular für Kündigung anlegen

  1. Neues Formular erstellen
    1. Benachrichtigung: Kündigung
    2. Weiterleitungsseite: nach Bedarf
  2. min. verstecktes Feld username und ein Absendefeld
  3. «Speichern und schließen»
  4. Formular im Frontend einbinden

5.5 IPN für Kündigung verarbeiten (optional)

Sobald die Kündigung durchgeführt wird, versendet Digistore eine IPN vom Typ on_rebill_cancelled. Hier könnte wieder über das Produkt darauf reagiert werden. So kann bei Kündigungseingang eine Mitgliedergruppe zugewiesen werden (z.B. Status Kündigung läuft). Außerdem könnte dem Kunden eine Kündigungsbestätigung per Mail gesendet werden.

6. Datenupdate bei Digistore durchführen

Der häufigste Anwendungsfall dafür ist die Änderung der E-Mail-Adresse eines Mitglieds. Wenn du ein Abo-Produkt anbietest, muss auch zeitgleich bei Digistore die E-Mail geändert werden. Seit Version 1.1.0 gibt es die Möglichkeit, dass du über die Digistore-API-Anbindung ein Update der Digistoredaten durchführen kannst.

6.1 API-Anbindung zu Digistore einrichten

Damit die API-Anbindung funktioniert, musst du zunächst wie unter «5.1 Kontozugriff bei Digistore einrichten» und «5.2 Ein neues Gateway für Digistore anlegen» beschrieben eine Verbindung herstellen.

6.2 Neue Benachrichtigung & Nachricht anlegen

6.2.1 Benachrichtigung

  1. Menüpunkt: Notification Center » Benachrichtigungen
  2. Neue Benachrichtigung
    • Titel: beliebig (z.B. E-Mail-Adresse ändern)
    • Benachrichtigungstyp: Mitglied: Persönliche Daten
  3. «Speichern und schließen»

6.2.2 Nachricht anlegen

  1. Neue Nachricht
    • Titel: beliebig (z. B. Datenupdate per API an Digistore)
    • Gateway: Digistore-API
    • Endpunkt: updateBuyer
    • Zuordnung Contao Feldnamen mit Digistorefeldern
      • Wert = Contao Feld (##member_email##)
      • Schlüssel = Digstore Feld (email)
    • Nachricht veröffentlichen: Ja
  2. «Speichern und schließen»

Bei den Parametern kannst du optional eine buyer_id angeben. Wenn keine angegeben ist, wird automatisch die beim Mitglied gespeicherte digistore_buyer_id geholt. Zudem könntest du auch andere Daten bei Digistore aktualisieren. Eine Liste der Felder findest du hier.

6.3 Modul für Änderung der Personendaten

Damit das Mitglied seine E-Mail-Adresse selbstständig ändern kann, benötigst du ein neues Frontend-Modul vom Typ Personendaten. Hier wählst du dann die editierbaren Felder aus. In unserem Beispiel wollen wir nur die E-Mail-Adresse auswählen. Außerdem die zuvor angelegte Benachrichtigung: E-Mail-Adresse ändern. Da das Mitglied nach der Änderung sofort abgemeldet wird, gibst du als Weiterleitungsseite am besten die Login-Seite an.

Dieses Modul bindest du zum Schluss dann auf einer entsprechenden Profil-Seite im Mitgliederbereich ein. Ab sofort sollten die Mitglieder Ihre Mailadresse selbstständig ändern können. Zusätzlich kannst du auch noch eine weitere Nachricht vom Typ E-Mail bei der Benachrichtigung hinzufügen, damit du bei jeder Änderung eine E-Mail bekommst.

7. Modul für Digistore Bestell-Informationen

Ab Version 1.2.x steht dir ein zusätzliches Frontend-Modul zur Verfügung, mit dem du über die Digistore-API Informationen zu Bestellungen abrufen kannst. Für Version 1.2 wird mindestens Contao 4.13 und PHP 8.1+ benötigt.

Um das Modul zu konfigurieren, benötigst du einen API-Schlüssel von Digistore. Diesen musst du im Modul hinterlegen. Wie du einen API-Schlüssel bei Digistore erstellen kannst, erfährst du in dem Abschnitt "5.1 Kontozugriff bei Digistore einrichten" oder direkt im Handbuch von Digistore.

Aktuell gibt es zwei Standardtemplates:

  • mod_digistore_order_infos_subscriptions
    Hier erhältst du Informationen zu Abonnements (Laufzeit, nächste Zahlung, Kündigungsdatum)
  • mod_digistore_order_infos_invoices
    Hier findest du eine Auflistung aller Rechnungen.

Die Templates und das CSS kannst du nach Bedarf anpassen und um weitere Felder anpassen. Aller verfügbaren Daten der Bestellung findest du in $this->orders.

8. Erweiterung entfernen / deinstallieren

  1. Backup erstellen
  2. Eintrag aus config.yml wieder entfernen
  3. Anpassungen in composer.json wieder rückgängig machen
  4. Alle Pakete aktualisieren über Contao Manager
  5. Installtool aufrufen und Datenbank bereinigen

Hinweis: Falls du das Notification-Center weiter nutzen willst, bitte vorher die Erweiterung über den Contao Manager hinzufügen.