Gini (JTL-Shop 5)
- Sebastian Meyer
- Pieter van der Vegt
- Maik Waffen
- 1 Einleitung
- 1.1 Features
- 2 Installation / Update
- 3 Konfiguration
- 3.1 Shop
- 3.1.1 Einstellungen
- 3.1.2 Template-spezifische Einstellungen (NOVA)
- 3.1.3 E-Mail-Templates
- 3.1.4 Zahlungsarteinstellungen
- 3.1.5 Versandartzuordnung
- 3.2 ERP-System
- 3.1 Shop
- 4 Betrieb
- 4.1 Shop
- 4.2 ERP-System
- 5 Individualisierung
- 5.1 Sprachvariablen
- 5.2 Templates
- 6 Troubleshooting
- 6.1 Logs prüfen
- 6.1.1 Browser-Log
- 6.1.2 Shop-Log
- 6.1.3 Webserver-Log
- 6.1 Logs prüfen
- 7 FAQ
- 8 Changelog
- 9 Support und Kontakt
Einleitung
Gini Pay bietet Ihnen die Möglichkeit, im JTL-Shop die Vorkasse Überweisung per QR-Code anzubieten.
Hierdurch werden fehlerhafte Überweisungen vermieden und die einfache Nutzung erlaubt dem Kunden schnell und direkt nach der Bestellung die Überweisung mit seiner bevorzugten Banking App auszuführen.
Features
Dieses Plugin bietet zwei neue Zahlungsarten an:
Vorkasse Überweisung
QR-Code Überweisung
Bei der Auswahl der Zahlungsart wird dem Kunden an drei Stellen ein QR-Code angezeigt, den er einfach nutzen kann, um mit seiner Banking App zu überweisen:
Auf der Bestellbestätigungsseite.
In der Bestellbestätigungsemail.
In der Detailansicht der Bestellung im Kundenkonto (bei registrierten Kunden).
Zusätzlich werden die gewohnten, konfigurierten Überweisungsdaten angezeigt, falls der Kunde doch manuell überweisen möchte.
Installation / Update
Systemvoraussetzungen
JTL-Shop 5 Version 5.2.0+ und dessen Voraussetzungen.
Plugin-Installation
Die Installation des Plugins erfolgt nach JTL-Standard, wie es hier beschrieben ist oder sie können Ihre vorhandene ZIP-Datei des Plugins auch über den Reiter “Upload“ in der Pluginverwaltung bereitstellen und anschließend im Reiter “Vorhanden“ die Installation starten.
Plugin-Update
Bei einem Update auf eine neuere Version können Sie der allgemeinen Installation folgen mit dem Unterschied, dass Sie direkt in der Pluginverwaltung den Update-Button zur Aktualisierung betätigen müssen.
Konfiguration
Shop
Einstellungen
Die Einstellungen finden Sie in der Admin-Oberfläche im Reiter Einstellungen.
Einstellung | Beschreibung |
|---|---|
API-Zugangsdaten | Geben Sie hier Benutzernamen und -passwort ein, die Sie von Gini erhalten haben. |
Zahlungsdaten | Geben Sie hier Ihre Bankdaten ein. Diese Daten werden dem Kunden zur Überweisung angezeigt und im QR-Code kodiert. Wichtig: Der Verwendungszweck unterstützt Smarty-Template-Logik. Seien Sie daher vorsichtig mit Anpassungen. Ihnen stehen das Objekt $Bestellung und $Kunde zur Verfügung. Beispielwert: Bestellung {$Bestellung->cBestellNr} Hinweis: Vermeiden Sie Sonderzeichen (wie z.B. #, €, @) im Verwendungszweck, da nicht alle Banken alle Zeichen unterstützen. |
Template / Frontend | Wählen Sie hier die Einhängepunkte und -methoden für die Darstellung in Bestellabschlussseite und in der Bestellansicht im Kundenkonto aus. (Siehe Template-spezifische Einstellungen) Wenn Sie “Zeige Manuelle Zahlungsinformationen” deaktivieren, wird dem Kunden nur der QR-Code ohne die Zahlungsdaten gezeigt (nicht empfohlen). |
Template-spezifische Einstellungen (NOVA)
Falls Sie den Standard-JTL-Erfolgstext und die Schaltfläche "Weiter einkaufen" ausblenden oder anzeigen möchten, steuern Sie dies über diese Einstellung. Durch das Ersetzen (replace) wird der Standard-Erfolgstext von JTL nicht mehr angezeigt, und auch die Schaltfläche "Weiter einkaufen" entfällt automatisch.
Einstellung | Wert |
|---|---|
PQ-Selector für die Zahlungsinformationen auf der Bestellabschluss-Seite |
|
PQ-Einfügemethode für die Zahlungsinformationen auf der Bestellabschluss-Seite |
|
E-Mail-Templates
Damit der QR-Code auch in der Bestellbestätigungsmail angezeigt werden kann, müssen Sie das Bestellbestätigungsmail-Template anpassen.
Fügen Sie für jede Sprache im HTML-Template den Code ein, wo die Information gezeigt werden soll:
{if isset($giniHtml)}{$giniHtml}{/if}Fügen Sie für jede Sprache im Text-Template den Code ein, wo die Information gezeigt werden soll:
Naturgemäß wird im Text-Teil der Mail kein QR-Code ausgegeben - hier wird auf die HTML-Ansicht verwiesen.
{if isset($giniText)}{$giniText}{/if}Zahlungsarteinstellungen
Die Einstellungen zur Zahlungsart entsprechen den Standardeinstellungen in JTL-Shop 5. Bitte ändern Sie nicht die Einstellung Zahlung vor Bestellabschluss, da die Zahlungsart sonst nicht angeboten wird. Die Einstellung muss auf “Nein” stehen.
Sie finden Zahlungsartlogos - falls Sie diese nutzen wollen - im Plugin-Pfad (z.B.: /plugins/s360_gini_shop5/logo.svg).
Versandartzuordnung
Die Zuordnung zu Versandarten entspricht dem Standard von JTL-Shop 5.
ERP-System
Wie bei allen Zahlungsarten, müssen Sie in der JTL-Wawi ebenfalls die Zahlungsarten so anlegen, dass die Namen in der Wawi den Anzeigenamen im Shop entsprechen. Nur so kann die JTL-Wawi die Zuordnung zur Zahlungsart richtig durchführen.
Die Option “Versand vor Zahlungseingang” sollte deaktiviert sein, da es sich um Vorkasse-Zahlungen handelt.
Betrieb
Shop
Im Plugin-Adminbereich im Reiter Zahlungen können Sie die mit Gini durchgeführten Bestellungen anschauen. Der Gini-Status zeigt Ihnen den Scan-Status von QR-Codes bzw. der Zahlung.
Die Bedeutungen sind dabei (ohne Gewähr, da diese von Gini gesetzt werden):
open → der QR-Code / Payment Request wurde erstellt und noch nicht in einer Banking-App gescannt.
qr_scanned → der QR-Code wurde in einer Banking App gescannt, aber noch nicht zwingend zur Auslösung einer Überweisung genutzt.
paid → der QR-Code wurde genutzt, um eine Überweisung auszulösen. (Achtung: Das bedeutet nicht automatisch, dass Sie auch einen Zahlungseingang erhalten!)
paid_adjusted → der QR-Code wurde genutzt, um eine Überweisung auszulösen, aber der Kunde hat Veränderungen an den Überweisungsdaten vorgenommen. (Achtung: Das bedeutet nicht automatisch, dass Sie auch einen Zahlungseingang erhalten!)
Das Plugin aktualisiert die Status der Zahlungen nicht proaktiv - wenn Sie den aktuellsten Stand eines Payment-Request sehen wollen, nutzen Sie bitte den “Angezeigte Zahlungen aktualisieren”-Button, um den aktuellen Status von Gini zu holen.
Hinweis: Je nach Integration zwischen Gini und der jeweiligen Bank entsprechen die von Gini gemeldeten Status ggf. nicht dem wirklichen Status. Es kann natürlich auch sein, dass ein Kunde die Überweisung in einer Banking App ohne Nutzung des QR-Codes ausführt, wodurch der Status nie von “open” weggeht, obwohl die Überweisung korrekt ausgeführt wurde. Diese sind daher nur als Anhaltspunkte zu verstehen.
ERP-System
Die Zahlungsart verhält sich aus Wawi-Sicht wie die Standard Vorkasse Überweisung - d.h. Sie müssen die eingehenden Überweisungen per HBCI o.ä. zu der Bestellung zuweisen - es erfolgt kein automatisches Setzen der Zahlung durch das Plugin weil das Plugin im Shop schlichtweg nicht weiß, ob eine Überweisung tatsächlich ausgeführt worden ist oder nicht.
Ebenso erfolgen Erstattungen etc. wie bei der Standard Vorkasse Überweisung und gehen nicht über das Plugin.
Individualisierung
Sie können Teile der Plugin-Ausgaben bei Bedarf auch individualisieren. Beachten Sie dabei, dass Sie nach Updates des Plugins Ihre Änderungen ggf. nachziehen müssen.
Sprachvariablen
Die Sprachvariablen finden Sie wie üblich im JTL-Shop 5 im Plugin-Manager in der Liste der installierten Plugins.
Templates
Die Template-Dateien im Pfad plugins/s360_gini_shop5/frontend/template sind individualisierbar, indem Sie eine *_custom.tpl in denselben Ordner legen.
Die CSS-Dateien werden auch über die Template-Dateien eingebunden - so können Sie hier auch Styles überschreiben.
Die Template-Dateien sind wie folgt unterteilt:
frontend.tpl → Anzeige im Bestellabschluss und in der Bestellansicht im Kundenkonto
email.tpl → HTML-Snippet für den HTML-Teil der Bestellbestätigungsmail
email_plain.tpl → Text-Snippet für den Text-Teil der Bestellbestätigungsmail
Troubleshooting
Logs prüfen
Um herauszufinden, wo ein Problem liegt, helfen Ihnen und uns die Logs. Je nach Fehlerbild ist eines der folgenden 3 Logs dafür mehr oder weniger relevant.
Browser-Log
Das Browser-Log ist meist relevant, wenn irgendwas im Frontend des Shops sich merkwürdig verhält oder nicht reagiert. (Beispiel: Sie klicken einen Button und augenscheinlich passiert gar nichts.)
Das Browser-Log sehen Sie, wenn Sie im Browser F12 drücken und dort dann auf Konsole (oder Console) wechseln.
Shop-Log
Das Shop-Log ist immer dann interessant, wenn im Frontend unerwartete Fehlermeldungen ausgegeben werden oder das Plugin zwar auf Eingaben im Frontend reagiert, aber nicht das Ergebnis liefert, was erwartet wurde. Manchmal ergibt sich auch durch das Browser-Log, dass die Informationen eher im Shop-Log zu suchen sind.
Das Shop-Log finden Sie im JTL-Adminbereich unter System → Wartung → Log.
Das JTL-Log arbeitet mit Log-Levels, um nicht die Datenbank unbegrenzt mit Logdaten zu befüllen. Im Umkehrschluss heißt das, dass Sie Logmeldungen aber auch erst dann sehen, wenn diese nach der Änderung des Loglevels erzeugt worden sind.
Das Plugin loggt außer kritischer Fehler fast ausschließlich im Debug-Log-Level. Wenn also etwas nicht klappt, sollten Sie zunächst das Debug-Loglevel aktivieren, dann eine Testbestellung durchführen, dann das Debug-Loglevel wieder deaktivieren und die zwischenzeitlich geloggten Meldungen zurate ziehen.
Webserver-Log
Das Webserver-Log wird dann relevant, wenn Sie irgendwo auf einen Error 500 (= weiße Seite) stoßen.
Das Webserver-Log kann Ihnen Ihr Hoster zur Verfügung stellen.
In der Standardkonfiguration loggt der JTL-Shop überhaupt nichts in das Webserverlog, nicht mal kritische Fehler wie einen Error 500.
Damit der Shop diese Fehler loggt, müssen in der /includes/config.JTL-Shop.ini.php die einzelnen *_LOG_LEVEL Werte von 0 auf E_ERROR geändert werden.
FAQ
Warum kommt das Plugin mit 2 Zahlungsarten, die identisch funktionieren?
Beide Zahlungsarten funktionieren zwar identisch, aber so können Kunden bei der Zahlungsartauswahl offensiver auf die Möglichkeit der QR-Code Überweisung hingewiesen werden, ohne die “bekannte” Vorkasse für weniger technisch versierte Kunden zu entfernen.
Es steht Ihnen natürlich frei, nur eine der beiden Zahlungsarten oder beide gleichzeitig zu nutzen.
Changelog
v1.0.3 (Feburar 2025)
Verbesserung: Darstellung Erfolgsmeldung nach QR-Code Scan
v1.0.2 (Januar 2025)
Bugfix: Tracking ID wird nicht korrekt in QR Code eingebettet
v1.0.1 (Januar 2025)
Bugfix Probleme mit dem SDK
v1.0.0 (Januar 2025)
Initiales Release
Support und Kontakt
siehe Support und Kontakt