Zahlungsarten als Plugin

Eine häufige Anwendungsart von Plugins in JTL-Shop3 sind zusätzliche Zahlungsarten.

Das Pluginsystem kennt eine besondere Pluginart, nämlich die Zahlungart (paymentmethod). Wird das Plugin als Zahlungsart definiert, kann eine Schablone genutzt werden, um die Zahlungsart zu integrieren.

Die Schablone ist eine Klasse in PHP, die von einer speziellen Zahlungsartklasse im Shopsystem erbt. Das Plugin muss die einzelne Methoden darin überschreiben, um die gewünschte Funktionalität zu erreichen.

Sobald eine Zahlungsart als Plugin installiert wurde, kann Sie im Adminbereich des Shops unter „Zahlungsarten“, wo auch alle anderen, dem Shopsystem zur Verfügung stehenden Zahlungsarten, aufgelistet sind, vom Shopbetreiber verwaltet werden. Zahlungsarten werden in JTL-Shop 3 Versandarten zugeordnet, d.h. jede Versandart kann unterschiedliche Zahlungsarten zulassen.
Wenn eine Zahlungsart getestet werden soll, sollte man demnach nicht vergessen, diese Zahlungsart einer Versandart zuzuordnen und im Bestellvorgang gewählt werden.

Je nach Zweck eines Plugins ist eine bestimmte Verzeichnisstruktur des Plugins nötig. Jedes Plugin hat im Rootverzeichnis eine XML-Datei namens info.xml, die das Plugin, seine Version, seine Aufgabe, usw. beschreibt. Die notwendige Verzeichnisstruktur für eine Zahlungsmethode wird in Paymentmethod Verzeichnisstruktur beschrieben. Der XML Aufbau einer Zahlungsmethode in der info.xml befindet sich in Zahlungsmethoden.

Aufbau

In diesem Abschnitt wird der Aufbau einer Zahlungsart als Plugin beschrieben. In erster Linie ist hierbei eine Klasse notwendig, die das Plugin mitliefern muss. Diese Klasse erbt von einer speziellen Zahlungsartklasse im Shopsystem und muss bestimmte Methoden überschreiben.

 <?php>
 include_once (PFAD_ROOT . PFAD_INCLUDES_MODULES . 'Paymentmethod.class.php')

 class PayPal extends PaymentMethod
 {

      function init()
      {
            $this->name = 'PayPal';
            $this->caption = 'PayPal';
      }

      // Zahlungsvorbereitung
      // Wie auch immer die Zahlungsmethode ausschaut, diese Methode bereitet alle Bestellungsdaten dafür vor.
      function preparePaymentProcess($order)
      {
            //overwrite!
      }

      // Setzt die Zahlung und informiert eventuell den Zahlungsanbieter
      function handleNotification($order, $hash, $args)
      {
            if($this->verfiyNotification($order, $hash, $args))
            {
                      //Zahlung setzen
                      //Aufräumen
                      //Emails senden
            }
      }

      // Wird bei einer Nachricht an die "notify.php" aufgerufen.
      // Return: bool, true/false
      function finalizeOrder($order, $hash, $args)
      {
             return $this->verifyNotification($order, $hash, $args);
      }

      // Erhält vom Zahlungsanbieter Daten und einen paymentHash die es zu verifizieren gilt.
      // Return: bool, true/false
      function verifyNotification($order, $paymentHash, $args)
      {
                       //Prüfe etwas und gib dann true oder false zurück
      }
 }
 ?>

Es gibt 2 Oberklassen von denen eine Zahlungsartklasse erben kann. Die PaymentMethod und die ServerPaymentMethod. Der Unterschied besteht darin, dass die ServerPaymentMethod noch mit einer weiteren Methode zum Senden von HTTP POSTS über Sockets ausgestattet ist.

Die definierten Methoden, die in der Klasse enthalten sein müssen lauten:

  • preparePaymentProcess($order)
  • handleNotification($order, $hash, $args)
  • finalizeOrder($order, $hash, $args)
  • verifyNotification($order, $paymentHash, $args)

JTL-Shop3 bietet zwei feste Abläufe, wie eine Zahlung durchgeführt werden kann:

  • Die erste Methode leitet den Zahlungsvorgang nach Abschluss der Bestellung ein. D.h. die Bestellung ist hierbei bereits abgeschlossen und in der Datenbank des Shopsystems.
  • Die zweite Methode bindet den Zahlungsvorgang während des Bestellvorgangs im Shop ein. Hier wird die Bestellung im Shop erst dann abgeschlossen, wenn der Zahlungsvorgang erfolgreich vom Kunden durchgeführt wurde. Wird der Zahlungsvorgang vom Kunden abgebrochen, so wird er ins Shopsystem zum Schritt Zahlungsart auswählen im Bestellvorgang zurückgeführt. Die Bestellung ist erst dann abgeschlossen, wenn der Zahlungsvorgang erfolgreich war, dann ist auch die Bestellung in der Datenbank des Shops enthalten. Es gibt hierbei zu beachten, dass nicht alle Zahlungsarten für eine Zahlung während des Bestellvorgangs geeignet sind. Zahlungsarten, die den Kunden nicht wieder in den Shop zurückleiten oder nur auf Umwegen zurück zum Shop bringen, sind nicht geeignet, da der Shop bei einer nicht angestoßenen Rückleitung die Bestellung nicht abschließen kann.

Das Zahlungsartplugin entscheidet sich in der info.xml für eine dieser beiden Methoden.

Die folgenden Ablaufpläne veranschaulichen diese beiden Methoden:

Bestellvorgang >> Zahlungsweiterleitung >> Bestellabschluss >> Zahlungseingang

Zahlungsvorgang während des Bestellvorgangs:

Der Vorteil bei dieser Methode ist, dass eine Bestellung oftmals schon als bezahlt in die Warenwirtschaft eingetragen werden kann, da eine Zahlung vor dem Bestellabschluss durchgeführt wird. Dadurch kann der Shopbetreiber seine Ware direkt versenden. Der Nachteil dieser Methode ist, dass Kunden, die den Zahlungsvorgang unkonventionell verlassen oder den Browser in diesem Schritt schliessen, verloren sind, da die Bestellung nicht in der Shopdatenbank abgelegt wird.

Bestellvorgang >> Bestellabschluss >> Zahlungsweiterleitung >> Zahlungseingang

Zahlungsvorgang nach abgeschlossener Bestellung:

Der Shopbetreiber hat auf jeden Fall die Bestellung als abgeschlossen im System. Er muss allerdings ggfs. selbst Zahlungseingänge beachten und verbuchen und erst dann kann die Ware verschickt werden. Unbezahlte Bestellungen können vom Shopbetreiber angesprochen werden.

Ablaufdiagramm eines Zahlungsvorgangs während des Bestellvorgangs:

Ablaufdiagramm eines Zahlungsvorgangs während des Bestellvorgangs

  • 1. Eine Instanz der Zahlungsklasse wird vom Plugin erstellt und die Methode preparePaymentProcess() mit der aktuellen Bestellung aufgerufen. Zwingenderweise wird in dieser Methode ein Sessionhash gebildet, der zum Zahlungsanbieter gesendet wird. Der Sessionhash muss vom Zahlungsanbieter in jedem Fall (Erfolg, Misserfolg, Abbruch) an das Shopsystem zurück übergeben werden. An diesem Sessionhash erkennt JTL-Shop3 eindeutig, um welche Bestellung es sich handelt. Der Sessionhash ist nicht die SessionID des Kunden im Shop, sondern ein speziell für den Zahlungsvorgang generierter, eindeutiger Hash. Weiterhin bereitet diese Methode alle Daten für den Zahlungsanbieter vor.
  • 2. Die Zahlungsklasse vom hat alle Zahlungsdaten vorbereitet und liefert dem Zahlungsanbieter diese über vom Zahlungsanbieter definierte Schnittstellen. Die Daten können z.B. für ein POST-Formular vorbereitet und an eine Templatedatei übergeben werden, die dann via Submit-Button den Shopbesucher zum Zahlungsanbieter weiterleitet. Nach der Weiterleitung übernimmt der Zahlungsanbieter den Shopkunden und führt ihn durch den Zahlungsvorgang. In diesem Schritt wird der Shopkunde auf die Seite vom Zahlungsanbieter weitergeleitet, sei es in Form eines IFrames im Shop, eines PopUps oder einer einfachen Weiterleitung, so dass der Shopkunde sich nicht mehr im Shop befindet, sondern auf den Zahlungsseiten des Zahlungsanbieters.
  • 3a Nach erfolgreicher Zahlung beim Zahlungsanbieter wird der Shopkunde wieder zurück in den Shop geleitet <ShopURL>/includes/modules/notify.php. Diese Rückleitung enthält meistens Zahlungsdaten und auch den Sessionhash aus 1.). Mit diesem Sessionhash wird die Session des Shopkunden reaktiviert und seine Bestelldaten sind abrufbar.
  • 3b Bei einem Abbruch seitens des Zahlungsanbieters, wird der Shopkunde im Normalfall, falls nicht anders geregelt, zum Shop geleitet <ShopURL>/bestellvorgang.php?editZahlungsart=1. Der Shopkunde befindet sich nun wieder im Schritt der Zahlungsartauswahl des Bestellvorgangs und kann nun eine evtl. andere Zahlungsart wählen.
  • 4. In diesem Schritt arbeitet die vom Shopsystem bereitgestellte notify.php die empfangenen Daten (per POST oder GET) vom Zahlungsanbieter ab. Die Bestelldaten des Shopkunden werden hierbei anhand des Sessionhashs geladen. Als nächstes wird die Methode finalizeOrder() der Zahlungsartklasse, die zuvor automatisch instanziiert wird, vom Plugin aufgerufen. Normalerweise ruft diese Methode eine Verifizierungsmethode auf verifyNotification(), die die Zahlungsdaten vom Anbieter verifiziert.
  • 5. Sind alle Daten korrekt verfiziert, wird die Methode handldeNotification() der jeweiligen Zahlungsklasse abgerufen. Diese Methode setzt die Zahlung.

Ablaufdiagramm eines Zahlungvorgangs nach Bestellabschluss:

Ablaufdiagramm eines Zahlungvorgangs nach Bestellabschluss

Bei dieser Methode sind viele Schritte mit denen aus einer Zahlung während des Bestellvorgangs identisch. Es ändert sich die Generierung eines Hashwertes und die Rückleitung im Fehlerfall.

Bei 3b.) kann ein Shopkunde bei einem Zahlungsvorgang nach Bestellabschluss natürlich nicht wieder zur Zahlungsartauswahl geleitet werden, sondern wird auf eine spezielle Seite (bestellab_again.php) gebracht, an der die Zahlung erneut angestoßen werden kann.

Zahlungsartauswahl im Frontend Screenshot

Der besondere Unterschied hierbei ist, dass bei Zahlungen nach Bestellabschluss ein Paymenthash generiert wird und während des Bestellvorgangs ein Sessionhash. Anhand des Hashs kann die Zahlungsartklasse das Verfahren erkennen und unterschiedlich behandeln.
Wenn der Zahlungsanbieter eine Nachricht an die notify.php schickt, muss immer darauf geachtet werden, dass einer der beiden Hashs mitgeschickt wird. Ein Paymenthash (ph) oder ein Sessionhash (sh), kann als GET oder POST Parameter vom Zahlungsanbieter geschickt werden.

Bild28.jpg - Ablaufdiagramm eines Zahlungsvorgangs während des Bestellvorgangs (88,478 KB) D. Hannappel, 30.11.2010 16:22

Bild29.jpg - Ablaufdiagramm eines Zahlungvorgangs nach Bestellabschluss (100,34 KB) D. Hannappel, 30.11.2010 16:23

Bild30.jpg - Zahlungsartauswahl im Frontend Screenshot (24,184 KB) D. Hannappel, 30.11.2010 16:23