/
Gini (JTL-Shop 5)

Gini (JTL-Shop 5)

Owned by Sebastian Meyer
Last updated: Mar 04, 2025 by Edward Rau
7 min read

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

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}
Bei komplexeren Anpassungen fragen Sie ggf. Ihren Servicepartner um Hilfe.

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

Einstellung

Wert

PQ-Selector für die Zahlungsinformationen auf der Bestellabschluss-Seite

#content

PQ-Einfügemethode für die Zahlungsinformationen auf der Bestellabschluss-Seite

Ersetzen (replace)

 

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.

Achtung: Editieren Sie die Config-Datei des Shops nur, wenn Sie wissen, was Sie tun! Fehlerhafte Anpassungen hier können Ihren Shop unerreichbar oder (verschlüsselte) Daten unbrauchbar machen. Im Zweifelsfall sollten Sie Ihren Hoster oder Servicepartner um Hilfe fragen.

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.

Warum wird mir die Zahlungsart nicht angezeigt, obwohl ich alles richtig konfiguriert habe?

Die Konfiguration des Plugins umfasst mehrere Aspekte. Neben der Eingabe der korrekten Zugangs- und Kontodaten, ist die Anpassung der Versandarten notwendig.

Falls bei Ihnen, trotz augenschlich korrekter Konfiguration, keine Gini-Zahlungsarten auftauchen, dann prüfen Sie bitte zunächst, ob Sie Ihre Versandarten aktualisiert haben. Bitte vergewissern Sie sich, dass die QR-Code Überweisung (Gini GmbH) und/oder Vorkasse Überweisung (Gini GmbH) zu Ihren jeweiligen Versandarten hinzugefügt und für die jeweiligen Kundengruppen verfügbar ist.

Sobald die Gini-Zahlungsarten in Ihren Versandarten hinterlegt sind, sollten diese auch bei der Auswahl verfügbar sein.

Falls Sie, nach Abschluss der Bestellung, keinen QR-Code sehen, so bitte berücksichtigen Sie den nachfolgenden Abschnitt.

Warum wird mir der QR-Code nicht angezeigt, obwohl ich alles richtig konfiguriert habe?

Die Konfiguration des Plugins umfasst mehrere Aspekte. Neben der Erfassung der Zahlungsart, unter den Versandarten, ist die Eingabe der korrekten Zugangs- und Kontodaten notwendig.

Falls bei Ihnen, trotz augenschlich korrekter Konfiguration, kein QR-Code im Bestellabschluss angezeigt wird, so prüfen Sie bitte zunächst Ihre Zugangsdaten. Bitte vergewissern Sie sich, dass diese korrekt gespeichert und ggf. aus Ihrem Passwort-Manager übernommen werden.

Anschließend können Sie Ihre Kontodaten überprüfen, achten Sie dabei, dass die IBAN und BIC keine Leerzeichen enthalten darf. Wenn diese Leerzeichen enthalten, dann führt dies zu einer fehlerhaften Verarbeitung, wodurch kein QR-Code angezeigt wird.

Die Zahlungsinformationen sollten beispielhaft so aussehen:

image-20250304-103150.png

Warum wird mir der QR-Code auf der Bestellabschlussseite, nicht aber in der Bestellbestätigung angezeigt?

Wenn Sie die Konfiguration des Gini-Plugins soweit erfolgreich abgeschlossen haben, können Sie Ihre E-Mail-Vorlagen anpassen. Bitte beachten Sie, dass der Code nicht innerhalb einer Bedingung platziert werden darf.

Es sollte eine Platzierung entweder vor {if…} oder nach {/if} erfolgen. Beachten Sie dabei, dass es sich über mehrere Zeilen erstrecken kann.

Ich benötige Hilfe bei der Integration, wie kann ich diese in Anspruch nehmen?

Wir bieten Ihnen einen, für Sie kostenfreien, Integrationsservice für die Einrichtung des Gini-Plugins an. Bitte füllen Sie dazu zunächst folgendes Formular aus: Gini Pay JTL Integrationsservice - Solution360

Anschließend können Sie ein Ticket bei uns im Service Desk erstellen, wir melden uns bezüglich der Terminabsprache bei Ihnen.

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

Related content