Einleitung

Dieses Plugin integriert die Zahlungsart Nets Easy in ihren JTL-Shop.

Nets (Network for Electronic Transfers) ist Teil der Nexi Group und bietet einfache, schnelle und sichere Zahlungslösungen an.

Das Nets Easy Plugin ermöglicht es Zahlungen über Nets Easy anzubieten.

Features

Frontend:

• Zahlungsart “Nets Easy”

Backend:

• Übersicht und Suche von Zahlungen

• Manuelle Zahlungsabwicklung (Full-/Partial- Charge und Refund)

• Konfigurationshilfe zum Plugin

Wawi:

• Stornieren aus der WAWI

• Automatischer Full-Charge bei Teilversand oder Komplettversand

Begriffsklärung

Ein reservierter Betrag ist zum Zahlungseinzug reserviert/autorisiert, aber es wurde darauf noch keine Zahlung eingezogen.

Ein Charge kann als Zahlungseinzug eines zuvor reservierten Betrages aufgefasst werden. Entsprechend bedeutet Full-Charge, dass der gesamte Bestellbetrag eingezogen wird.

Ein Refund ist eine Erstattung einer zuvor erfolgten Charge.

Ein Cancel ist der Abbruch einer reservierten Zahlung vor dem Zahlungseinzug.

Installation / Update

Systemvoraussetzungen

• JTL-Shop 5.0.0 und dessen Voraussetzungen

Weitere Voraussetzungen

Sie benötigen ein Händlerkonto, registrieren Sie sich unter https://portal.dibspayment.eu/registration.

Open

Registrierung

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.

Wir empfehlen die Installation über den JTL-Extension-Store, damit Sie regelmäßig auf Updates hingewiesen werden und diese per Knopfdruck ausführen können.

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

Das Plugin unterstützt Sie bei der Einrichtung der Zahlungsart, wählen Sie dafür den Reiter “Hilfe“ im Plugin aus. Sie erhalten dort eine Übersicht über die Konfiguration. Überprüfen Sie an der Stelle die von Ihnen hinterlegten Einstellungen zu den Zahlungs- und Versandarten.

Zahlungsarten

Die Konfiguration der Zahlungsart erfolgt über die Standard-Verwaltung im JTL-Shop. Sie finden die Zahlungsarten unter Administration → Zahlungsarten. Einen direkten Link dahin finden Sie auch auf der Hilfe-Seite des Plugins. Wählen Sie Nets Easy über das Stift-Symbol aus und konfigurieren Sie die Zahlungsmethode bei Bedarf.

Logo einstellen

Hier können Sie das Zahlungsartlogo anpassen oder entfernen. Im Idealfall sollte es zu den von Ihnen mit netsEasy vereinbarten Zahlungsanbietern passen.

Eine Reihe von Beispiel-Logos finden Sie im Plugin-Verzeichnis (<Shop>/plugins/s360_netseasy_shop5/paymentmethod/images). Sie können aber auch ihre eigenen im Shop hochgeladenen Bilder verwenden.

Geben Sie hier immer eine absolute URL (mit https:// beginnend) an.

Plugin-Einstellungen

Neben den Standard-Einstellungen für Zahlungsarten befinden sich im Plugin unter Einstellungen die Einstellungen zur Zahlungsart.
Hier können Sie die für den Betrieb im Plugin notwendigen Daten aus ihrem Nets Easy Account hinterlegen.

Versandarten

Weisen Sie nun Nets Easy den gewünschten Versandarten/Ländern unter Administration → Versand zu. Das Plugin berücksichtigt auch etwaige Aufschläge zur Zahlungsmethode. Einen direkten Link dahin finden Sie auch auf der Hilfe-Seite des Plugins.

JTL-Wawi

Damit die über Nets Easy getätigten Zahlungen in der JTL-WAWI den Bestellungen zugeordnet werden, sind hier weiterführende Einstellungen vorzunehmen.

Zahlungsart einrichten

Öffnen Sie in der JTL-WAWI die Zahlungsartenverwaltung über Zahlungen → Zahlungsarten.

Legen Sie als Zahlungsart Online Checkout an, oder eine Zahlungsart mit dem Namen, den Sie als Anzeigenamen im Shop angegeben haben. Beachten Sie, dass die Zahlungsarten in jeder Sprache dem jeweiligen “angezeigten Namen“ im JTL-Shop entsprechen müssen, da die Wawi sonst die Zuordnung nicht herstellen kann.

Standardmäßig ist der Zahlungseinzug auf sofort eingestellt. Falls sie Sich jedoch für Zahlungseinzug beim ersten Teilversand oder erst bei Komplettversand entscheiden, muss “Auslieferung vor Zahlungseingang möglich“ aktiviert werden. Der Full-Charge wird dann abhängig von den Plugin Einstellungen mit dem nächsten Wawi-Abgleich ausgeführt.

Open

Betrieb

Shop

Frontend

Die Zahlungsart Nets Easy steht Kunden nur unter bestimmten Voraussetzungen zur Verfügung.

Ihr Shop muss die Währungen Dänische Krone, Euro, Britisches Pfund, Norwegische Krone, Schwedische Krone, US-Dollar, Polnische Zloty oder Schweizer Franken unterstützen.

Backend

Im Plugin-Backend können Sie die Bestellungen einsehen, die mit Nets Easy bezahlt wurden. Die Suche unterstützt Sie dabei die gewünschten Bestellungen zu finden.

Aktionen

Anzeigen - Klicken Sie auf das Auge-Symbol, um die Details der Zahlung anzuzeigen. Neben den Bestelldaten und Zahlungsinformationen werden hier auch die Charges und Rückzahlungen aufgelistet (siehe Zahlungsdetailseite). Diese Aktion ist immer möglich.

Charge - Klicken Sie auf das Dollar-Symbol, um eine Full-Charge durchzuführen. Der insgesamt reservierte Betrag wird dabei gechargt. Diese Aktion ist möglich solange der Zahlungsstatus “reserviert” ist.

Stornieren - Klicken Sie auf das Stopp-Symbol, um die Zahlung zu stornieren. Der insgesamt reservierte Betrag wird dem Kunden freigegeben. Diese Aktion ist möglich solange der Zahlungsstatus “reserviert” ist.

Erstatten - Klicken Sie auf das Undo-Symbol, um einen Full-Refund durchzuführen. Der insgesamt gechargte Betrag wird dem Kunden zurückgezahlt. Diese Aktion ist möglich solange der Zahlungsstatus “charged” ist.

Zahlungsdetailseite

Auf der Zahlungsdetailseite werden die Informationen dargestellt, welche von Nets Easy zu der Zahlung bereitgestellt werden. Dazu gehören Kunden-, Zahlungsinformationen sowie Rechnungs- und Versandadresse. Sofern das Debugging für das Backend aktiviert ist werden die Rohdaten der Transaktion darüber angezeigt.

Die nachfolgenden Bestellpositionen werden aus dem Shop-Warenkorb geladen und können über die Checkboxen für einen teilweisen Charge bzw. eine teilweise Rückzahlung ausgewählt werden. Die partiellen Aktionen (partial charge / partial refund) sind nur auf der Zahlungsdetailseite verfügbar.

Bei erfolgreicher Durchführung einer Aktion oder wenn ein Fehler bei der Abarbeitung auftritt, dann werden Sie im Backend im Info-Bereich der Zahlungsübersicht mit der entsprechenden Fehlermeldung darüber informiert. Diese Meldung wird auch im Shop geloggt.

Wurde einmal partiell gechargt, dann kann kein Full-Charge mehr durchgeführt werden. Sie müssen den Restbetrag über einen oder mehrere weitere partielle Charges “chargen”.

Die Bestellmengen der Bestellpositionen werden um die Anzahl der gechargten Mengen heruntergezählt. Ist eine Bestellposition bei 0, dann kann kein weiterer Charge hierfür durchgeführt werden. Für eine bessere Übersicht wird die initiale Menge neben dem Eingabefeld angezeigt. Wurde der komplett reservierte Betrag gechargt, dann wird der Button teilweise Chargen nicht mehr angezeigt.

Zu jedem Charge können Sie einen Full-Refund oder ein oder mehrere partielle Refunds durchführen. Charge-übergreifende Refunds sind nicht möglich.

Ein zweiter partieller Refund ist nur dann durchführbar, wenn der Refund zuvor erfolgreich abgeschlossen wurde bzw. erfolgreich storniert werden konnte. Das Abbrechen eines Refunds ist nur solange möglich wie sich ein Refund im Status “Pending“ befindet, solange wird auch der Button “Erstattung abbrechen“ angezeigt.

Rundungsdifferenzen

Bei der Erstellung einer Zahlung bzw. Rückzahlung kann es zu Rundungsdifferenzen kommen. Vor allem bei Teilzahlungen und Teilrückzahlungen für Warenkorb-Positionen. Das Plugin nutzt die JTL-Shop Warenkorb-Positionen und das JTL-eigene Berechnungsverfahren. Es ist damit in der Lage Rundungsdifferenzen auszugleichen, da alle Beträge einer einheitlichen und genaueren Berechnung zugrunde liegen. Ausgleichspositionen anzulegen ist in diesem Fall nicht mehr notwendig.

Abweichungen zu den im Nets Easy Backend sind dadurch unvermeidbar, weil nur zwei Nachkommastellen Berücksichtigung finden und nicht wie bei JTL-Shop wesentlich mehr.

Um etwaige Rundungsdifferenzen im Nets Easy Backend auszugleichen müssen Sie eine Ausgleichsposition einfügen und die Summe der Positionen an die Gesamtsumme der Charge bzw. Erstattung angleichen.

Kauf mit Guthaben

Bei der Verwendung von Guthaben ist bei JTL zu beachten, dass dieses Guthaben de facto keine Position im Warenkorb einnimmt. Es wird pauschal vom Gesamtbetrag abgezogen. In dem Fall stimmt allerdings die Gesamtsumme der Warenkorb-Positionen nicht mehr mit dem Gesamtbetrag der Bestellung überein.

Um dies dennoch angleichen zu können wird eine Pseudo-Warenkorb-Position an die Nets Easy Zahlung angefügt und wie eine normale Position in dem Zahlungsprozedere behandelt. Guthaben sowie auch Gutscheine stellen negative Positionen im Warenkorb da.

Gutscheine und Coupons

Gutscheine und Coupons werden als Warenkorb-Position geführt und sollten genauer in Betracht gezogen werden, wenn Teilzahlungen oder Teilrückzahlungen durchgeführt werden. Da diese, wie Guthaben, negative Positionen darstellen ist bei der Zahlungsdurchführung darauf zu achten, dass die Gesamtbeträge weder überschritten noch negativ werden dürfen. Ist dies dennoch der Fall wird Nets Easy die Aktion mit einem API-Fehler verweigern.

Wawi

Eingehende Bestellungen und mit Nets Easy durchgeführte Zahlungseingänge werden durch Abgleich an die JTL-WAWI übertragen. Über die WAWI können nur die Aktionen Full-Charge (in Abhängigkeit vom Zahlungseinzug) und Cancel (Storno) ausgeführt werden.

Bestellung bezahlen (Full-Charge)

Je nach Plugin-Einstellung zum Zahlungseinzug (vergl. Tab. 1) sind die Bestellungen bereits gechargt. Nur im Fall von Zahlungseinzug bei erstem Teilversand oder bei Komplettversand sind erweiterte Einstellungen vorzunehmen (siehe Zahlungsart einrichten). Der Full-Charge wird dann im Anschluss an den WAWI-Abgleich bei Nets-Easy durchgeführt.

Bestellung stornieren (Cancel)

1. Gehen Sie in die JTL-WAWI → F6 → Auftrag wählen → rechte Maustaste → Storno → Stornieren

2. Führen Sie anschließend einen Onlineshop Abgleich durch

Der Full-Charge wird dann im Anschluss an den WAWI-Abgleich bei Nets-Easy durchgeführt.

Individualisierung

Die Zahlungsart wird in der Standardauswahl der Zahlungsarten im JTL-Shop eingeblendet und hat keine individualisierbaren Elemente an der Stelle.

Wenn Sie ein eigenes Template verwenden und den Embedded Checkout nutzen möchten, dann sind ggf. erweiterte Einstellungen vorzunehmen. Sofern Ihr Template nicht auf dem NOVA-Template basiert, oder an der Stelle grundlegende Änderungen vorgenommen wurden, dann können sie im Bereich Einstellungen > Embedded Checkout ein alternatives Element angeben an dem der Embedded Checkout angebunden wird.

Achten Sie darauf, dass der “Zahlungspflichtig bestellen“-Button ausgeblendet wird bzw. nicht sichtbar ist und der Kunde nur über das eingebunden IFrame den Kauf abschließen kann.

FAQ

Warum gibt es Status und einmal letzter Status in der Übersicht im Plugin Backend?

Der erste Status ist der Nets Easy Status der Zahlung, dieser wird in Abhängigkeit der Beträge zueinander von Reserviert, Charge und Erstattet bestimmt. Der letzte Status ist der resultierende Status aus der zuletzt ausgeführten Aktion zu der Zahlung im Backend. Wird eine Zahlung über das Nets Easy Backend verwaltet, so wird diese Aktion über einen Webhook an das Plugin übermittelt und die Zahlung im Shop aktualisiert.

Warum werden mir Status und die Aktion-Buttons nicht angezeigt?

Der Status und die Aktion-Buttons werden nur dann angezeigt, wenn die API-Schlüssel unter Einstellungen eintragen sind. Bitte achten Sie darauf die Schlüssel korrekt zu übertragen, anderenfalls wird Ihnen die Meldung angezeigt:

Warum werden bei machen Zahlungen Erstattungen angeboten und bei anderen nicht?

Wird die Aktion Erstattung auf der Übersicht angeboten, dann wurde diese Zahlung über ein Full-Charge bezahlt. Anderenfalls ist der volle Betrag über mehrere Partial-Charges bezahlt worden. Full-Charges können über den Full-Charge-Button oder über die WAWI ausgelöst werden.

Über die WAWI können nur Full-Charges ausgeführt werden. Das kann einmal für den ersten Teilversand oder beim Komplettversand eingestellt werden.

Warum kann ich keinen freien Charge- oder Erstattungsbetrag im Plugin Backend angeben?

Das Plugin berechnet die Gesamtsummen für Charges oder Erstattungen aus dem JTL-Warenkorb. Damit stellen wir sicher, dass für die Ermittlung der Beträge stets das JTL-eigene Berechnungsverfahren zugrunde liegt. Damit werden Rundungsfehler minimiert, wenn Sie Teilmengen zu einer Bestellposition chargen oder erstatten.

Warum ist useCredit (Verrechnetes Guthaben) als Position in der Bestellung?

Bezahlt der Kunde mit Guthaben aus seinem Kunden-Account, dann entstehen gegenüber Nets Easy Inkonsistenzen. Guthaben wird im JTL-Shop einmalig vom Gesamtbetrag abgehalten und ist nicht Position der Bestellung. Nets Easy hingegen erwartet, dass die Gesamtsumme aller Positionen mit dem Gesamtbetrag übereinstimmen, dafür müsste das Guthaben Position der Bestellung sein.

Guthaben wird hier letztendlich als Pseudo-Element der Bestellung einmalig hinzugefügt, um diese Inkonsistenz auszugleichen.

Edge Cases (Randfälle)

Letzter bzw. ausverkaufter Artikel

Es kann passieren, dass Kunden um den letzten Artikel konkurrieren.

Troubleshooting

Sollten Sie Probleme mit dem Plugin beobachten, prüfen Sie zunächst die Logs und wenden Sie sich ggf. an unseren Support oder Ihren Service-Partner, wenn Sie das Problem nicht selbständig lösen können.

Je mehr Informationen Sie dem Support bei einem Problem geben können, desto eher sind wir in der Lage, Ihnen zu helfen. Nicht reproduzierbare Probleme sind dagegen auch nur schwer zu analysieren.

Meldungen

Diese Meldung wird angezeigt, wenn der Kunde versehentlich auf der Zusammenfassungsseite die Währung auf eine von Nets Easy nicht unterstützte Währung gestellt hat. Er wird auf die Versand- und Zahlungsartseite zurückgeleitet und kann eine passend zur gewünschten Währung Zahlungsart auszuwählen oder die gewünschte Währung so zu ändern, sodass Nets Easy als Zahlart wieder zur Verfügung steht.

Diese Meldung wird angezeigt, wenn der Kunde im Nets Easy Checkout auf “< Go back“ geklickt hat und die Zahlung abbricht ohne den Checkout zu durchlaufen.

In manchen Fällen kann es dazu kommen, dass die Zahlung nicht sofort bestätigt werden konnte. Dies ist z.B. dann der Fall, wenn es zeitliche Verzögerungen gibt zwischen dem Zurückleiten des Kunden auf die Return-URL und der Verarbeitung der Zahlung. In diesem Fall wird der Kunde auf eine Warteschleife gesetzt. Die Warteschleife prüft periodisch (max. 60 Sekunden) den Eingang eines Callbacks von Nets Easy für die aktuelle Payment-Id. Sollte nach Ablauf der Wartezeit kein Callback über den Webhook eintreffen, dann wird die Zahlung bei Nets Easy storniert und die obige Meldung angezeigt.

Diese Meldung wird angezeigt, wenn die Zahlung zwischenzeitlich abgebrochen oder storniert wurde.

Diese Meldung wird angezeigt, wenn der Charge nicht durchgeführt werden konnte. Die Zahlung wurde bei Nets Easy storniert. Prüfen Sie das Shop-Log.

Diese Meldung wird angezeigt, wenn der Charge nicht durchgeführt werden konnte. Die Zahlung wurde bei Nets Easy storniert. Prüfen Sie das Shop-Log.

Diese Meldung wird angezeigt, wenn der API-Client mit invalider Konfiguration initialisiert wird. Prüfen Sie das Shop-Log.

Diese Meldung wird angezeigt, wenn es zu Fehler in der Kommunikation mit der Nets Easy API gekommen ist. Gründe dafür können invalide Eingabezeichen oder fehlerhafte API-Credentials sein. Prüfen Sie das Shop-Log.

Diese Meldung wird angezeigt, wenn es zu einem Fehler auf der Kommunikationsebene gekommen ist. Interne Daten können nicht validiert werden oder es besteht ein internes Problem, dass die Kommunikation mit Netz Easy verhindert.

Logs prüfen

Im Plugin-Backend werden dem Händler zu jeder Aktion Erfolgs- und Fehlermeldungen angezeigt. Das Plugin loggt prinzipiell sämtliche Aktionen ins Shop-Log (Debug-Level). Alle entsprechenden Meldungen und die allgemeine Kommunikation mit der Nets Easy API kann dann bequem mit dem Präfix “NETSEASY>“ gefiltert werden.

Aktivieren Sie dafür zuerst in den Logbuch-Einstellungen das Debugging. Aktivieren Sie in den Plugin-Einstellungen das Debugging, falls benötigt:

Frontend

• Gibt zusätzliche Informationen des Notification-Endpunktes aus (Anfragen der Warteschlange)

• Gibt den kompletten RetrievePaymentResponse des Return-Endpunktes aus.

• Gibt zusätzliche Informationen über die Verarbeitung der Callbacks im Webhook-Endpunkt aus.

Backend

• Gibt die Curl-Optionen im API-Client aus.

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.

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.

Changelog

v1.1.3 (Oktober 2024)

• Neue zahlungsart: Klarna

v1.1.2 (August 2024)

• Verbesserungen: Handling veralteter Dateien nach Plugin-Update

v1.1.1 (August 2024)

• Verbesserung: Smarty issue

• Fix: Bugfixes und code optimierung

v1.1.0 (Juli 2024)

• Fix: Probleme mit Rundungsdifferenzen behoben

• Verbesserung: JTL 5.3 + PHP 8.3 Kompatibilität

• Verbesserung: Aufsplitten der kombinierten Zahlungsart in eigenständige Zahlungsarten (die kombinierte Zahlungsart ist weiterhin verfügbar)

  • Kreditkarte

  • Trustly

  • Sofort

  • MobilePay

  • PayPal

  • ApplePay

  • SEPA Lastschrift

  • Ratepay Rechnungskauf

  • Riverty Rechnung

  • Riverty Ratenzahlung

v1.0.7 (August 2023)

• Verbesserung: Webhook-Handling loggt spezifischere/hilfreichere Informationen

• Verbesserung: Interne Admin-Mails mit Informationen zu betroffenen Bestellungen / Payment-IDs angereichert
  Achtung: Die E-Mail-Templates werden nicht automatisch bei Plugin-Updates aktualisiert. Sie müssen die E-Mail-Templates vom Plugin manuell im Shop-Admin zurücksetzen um die verbesserten Templates zu nutzen.

v1.0.6 (Juli 2023, unreleast)

• Verbesserung: Übergabe von ArtNr statt interner Artikel-ID an NetsEasy für bessere Referenzierung

• Verbesserung: Ausschließliche Verwendung der Payment-ID als Transaktions-ID, um automatische Verarbeitung zu erleichtern

• Verbesserung: Backend-URLs nach JTL-Shop 5.2.x Logik, wenn > 5.2.0

• Fix: Prüfung auf existierende Tabellenspalte in Migration

v1.0.5 (Mai 2023)

• Überarbeitung der Zahlungslogik, um eingebetteten und weitergeleiteten Checkout, sowie verschiedene Zahlungsanbietern zu supporten

• Umbenennung der (initialen) Anzeigenamen in “Online Checkout”

• Auslieferung von initialer Zahlungsartbeschreibung und Zahlungsartlogos zur Verwendung im Shop

• Mehr Debugmeldungen und Optionen, diese zu aktivieren

• div. Verbesserungen

v1.0.4 (unreleast)

v1.0.3 (Februar 2023)

• Fix Bestellungen werden nach erfolgreicher Zahlung nicht angelegt!

v1.0.2 (Januar 2023)

• Update Exsid

v1.0.1 (November 2022)

• Kompatibilität mit JTL-Shop 5.2

• Fix Embedded Checkout Link

v1.0.0 (August 2022)

• Initiales Release

Support und Kontakt

siehe Support und Kontakt