Barzahlen (JTL-Shop 5)

Einleitung

Dieses Plugin integriert die Zahlungsart Barzahlen (viafintech) in Ihren JTL-Shop.

Barzahlen ermöglicht es Bestellungen zu bezahlen, ohne dem Händler Zahlungsinformationen Preis zu geben. Bei einer Bestellung erhält der Kunde einen Zahlschein, mithilfe dessen er den Betrag der Bestellung in einer Partnerfiliale bar bezahlen kann. Die Partnerfiliale meldet die Bezahlung an Barzahlen (viafintech) und anschließend wird per Webhook der Online-Shop über die eingegangene Zahlung informiert.

Features

Frontend:

  • Zahlungsart Barzahlen

Backend

  • Übersicht der Zahlungen mit Barzahlen (viafintech)

  • Suche und weitere Aktionen auf Zahlscheine (Erstatten, Senden, Invalidieren)

  • Konfigurationshilfe zum Plugin

Installation / Update

Systemvoraussetzungen

  • JTL-Shop 5.00+ und dessen Voraussetzungen

Weitere Voraussetzungen

  • Sie müssen sich im Barzahlen (viafintech) Control Center registrieren

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 anschliessend 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

JTL-Shop

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

Zahlungsarten

Die Konfiguration der Zahlungsart erfolgt über die Standard-Verwaltung im JTL-Shop. Sie finden die Zahlungsarten unter Storefront → Zahlungsarten → Übersicht. Einen direkten Link dahin finden Sie auch auf der Hilfe-Seite des Plugins.

Wenn Sie für die Zahlungsart lieber ein Logo statt einfachen Text verwenden möchten, finden Sie in “/includes/plugins/s360_barzahlen_shop5/paymentmethod/images” eine Auswahl von Logos, welche sie unter der Bild-URL angeben können.

Aus technischen Gründen muss die Option “Zahlung vor Bestellabschluss” auf “Ja” stehen. Sonst wird die Zahlungsart nicht angeboten.

Neben den Standard-Einstellungen für Zahlungsarten finden sich hier insbesondere die übergeordnete Einstellungen zur Zahlungsart Barzahlen

Option

Bedeutung

Standard

Option

Bedeutung

Standard

Rechnungsadresse senden

Ist diese Option aktiviert, dann wird die Rechnungsadresse des Kunden an Barzahlen (viafintech) mitgesendet, damit kundennahe Barzahlen Partner-Filialen zum Zahlschein angezeigt werden können.

Ja

Zahlschein Gültigkeitsdauer

Gibt die Gültigkeitsdauer des Zahlscheins in Tagen an. (Dies ist nur erlaubt, wenn dies auch vertraglich mit Barzahlen (viafintech) vereinbart wurde.)

-

sowie den Betriebsmodus und die API-Zugangsdaten der länderspezifischen Divisionen. Erstellen Sie im Barzahlen (viafintech) Control Center eine Division unter Einstellungen → Divisionen. Pro Geschäftsland kann seitens Barzahlen (viafintech) nur eine Division angelegt und anschliessend für den Live-Betrieb aktiviert werden.

Option

Bedeutung

Standard

Option

Bedeutung

Standard

[DE] Deutschland

Aktivieren Sie hier die vorgesehene Division für Deutschland, indem Sie diese in den Sandbox- oder Live-Modus setzen.

nicht aktiv

[DE] Division-ID

Geben Sie hier die Division-ID für Deutschland an.

-

[DE] API-Key

Geben Sie hier den API-Key der entsprechenden Division-ID ein.

-

[AT] Österreich

Aktivieren Sie hier die vorgesehene Division für Österreich, indem Sie diese in den Sandbox- oder Live-Modus setzen.

nicht aktiv

[AT] Division-ID

Geben Sie hier die Division-ID für Österreich an.

-

[AT] API-Key

Geben Sie hier den API-Key der entsprechenden Division-ID ein.

-

[IT] Italien

Aktivieren Sie hier die vorgesehene Division für Italien, indem Sie diese in den Sandbox- oder Live-Modus setzen.

nicht aktiv

[IT] Division-ID

Geben Sie hier die Division-ID für Italien an.

-

[IT] API-Key

Geben Sie hier den API-Key der entsprechenden Division-ID ein.

-

[CH] Schweiz

Aktivieren Sie hier die vorgesehene Division für die Schweiz, indem Sie diese in den Sandbox- oder Live-Modus setzen.

nicht aktiv

[CH] Division-ID

Geben Sie hier die Division-ID für die Schweiz an.

-

[CH] API-Key

Geben Sie hier den API-Key der entsprechenden Division-ID ein.

-

[GR] Griechenland

Aktivieren Sie hier die vorgesehene Division für Griechenland, indem Sie diese in den Sandbox- oder Live-Modus setzen.

nicht aktiv

[GR] Division-ID

Geben Sie hier die Division-ID für Griechenland an.

-

[GR] API-Key

Geben Sie hier den API-Key der entsprechenden Division-ID ein.

-

[<Land-ISO-Code>] Land

Allgemein: Aktivieren Sie hier die vorgesehene Division für das Land, indem Sie diese in den Sandbox- oder Live-Modus setzen.

nicht aktiv

[<Land-ISO-Code>] Division-ID

Allgemein: Geben Sie hier die Division-ID für das Land an.

-

[<Land-ISO-Code>] API-Key

Allgemein: Geben Sie hier den API-Schlüssel für das Land an.

-

Für eine gültige API-Konfiguration muss mindestens eine Division aktiviert und die dazu gehörigen API-Zugangsdaten (Division-ID/API-Key) angegeben werden.

Versandarten

Weisen Sie nun die Zahlungsart Barzahlen den gewünschten Versandarten/Ländern unter Storefront → Kaufabwicklung → Versandarten zu. Einen direkten Link dahin finden Sie auch auf der Hilfe-Seite des Plugins.

Beachten Sie, dass Barzahlen ausschließlich nur in Deutschland, Österreich, Italien, der Schweiz und Griechenland zur Verfügung steht.

Befindet sich die Rechnungsadresse des Kunden in einem anderen Land, dann wird die Zahlungsart nicht angeboten.

JTL-Wawi

Zahlungsart einrichten

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

Legen Sie die Zahlungsart Barzahlen an.

Beachten Sie, dass die Zahlungsarten dem Anzeigenamen im JTL-Shop entsprechen müssen. D.h., falls Sie im Shop die angezeigten Namen ändern oder auch für andere Sprachen übersetzen, müssen Sie dies hier ebenfalls anpassen.

Barzahlen (viafintech) Control Center

Das Barzahlen Plugin übermittelt für jeden Zahlschein eine Benachrichtigungs-URL (Webhook), diesen Webhook finden Sie (wie oben erwähnt) auf der Hilfe-Seite des Barzahlen Plugins. Daher sind hier keine weiteren Einstellungen nötig.

Betrieb

Shop

Frontend

Die Zahlungsart Barzahlen steht Kunden nur unter gewissen Voraussetzungen zur Auswahl zur Verfügung.

Ihr Shop muss Deutschland, Österreich, Italien, Schweiz oder Griechenland als Rechnungsland unterstützen und die Währungen Euro und Schweizer Franken anbieten.

Der über Barzahlen zahlbare Gesamtbetrag ist länderspezifisch und limitiert auf:

Länder

Limit

Länder

Limit

Deutschland, Italien, Österreich, Frankreich, Spanien (EU/EUR)

999.99 Euro

Schweiz (non EU/CHF)

1500 SFr.

Griechenland (EU/EUR)

499.99 Euro

Wird das Limit bei der Bestellung überschritten, dann wird Barzahlen nicht als Zahlungsart angeboten. Dies gilt auch für Rabatte oder etwaige Gebühren der Zahlungsart, diese werden berücksichtigt und mit eingerechnet.

Das Limit bezieht sich auf die letzten 24 Stunden und gilt pro Kunde pro Division. Das Plugin berechnet das Limit eines jeden Kunden und bietet die Zahlungsart an, sofern das Tageslimit noch nicht überschritten ist.

Backend

Im Plugin-Backend können Sie im Reiter “Zahlungen” die Zahlungen einsehen, die mit Barzahlen bezahlt wurden. Die Suche unterstützt Sie dabei die betreffenden Informationen zu finden. Geben Sie hier mindestens 3 Zeichen ein, um in Bestellnummer, Zahlschein oder Betrag zu suchen.

Spalte

Bedeutung

Spalte

Bedeutung

BestellNr

Bestellnummer im Onlineshop

Zahlschein

ID des Barzahlen Zahlschein ( SlipID )

Division

Barzahlen Division ID

Typ

Zahlschein-Typ (payment/refund)

Status

Status des Zahlscheins (pending/paid/expired/invalidated)

Betrag

Betrag in EUR/CHF

Storno

Summe der aktiven oder ausgezahlten Rückzahlungen (pendig/paid)

Land

Rechnungsland der Bestellung

Lieferung

Lieferland der Bestellung

Ablauf

Ablaufdatum des Zahlscheins

Aktionen

Anzeigen, Erstatten, Senden oder Invalidieren

Aktionen

Anzeigen - Klicken Sie auf das Auge-Symbol, um die Details des Zahlscheins anzuzeigen. Neben den Zahlungsinformationen werden hier auch die Rückzahlungen aufgelistet.

Erstatten - Klicken Sie auf den Undo-Pfeil, um eine Rückzahlung anzuweisen. Im Eingabefeld ist der komplette Rechnungsbetrag vorgegeben, Sie haben jedoch die Möglichkeit auch einen Teilbetrag zu erstatten. Bestätigen Sie mit “Erstatten”, um die Aktion auszuführen.

Senden - Klicken Sie auf den Rechts-Pfeil, um den Zahlschein an die vom Kunden hinterlegte E-Mail-Adresse erneut zu versenden. Bestätigen Sie mit “Senden”, um die Aktion auszuführen.

Invalidieren - Klicken Sie auf das Kreuz, um den Zahlschein zu invalidieren. Bestätigen Sie mit “Invalidieren”, um die Aktion auszuführen.

JTL-Wawi

Eingehende Bestellungen und getätigte Zahlungen werden von der JTL-Wawi durch den Onlineshop-Abgleich eingelesen und verarbeitet (siehe Zahlungsart einrichten).

Bestellung stornieren

  • Gehen Sie in die JTL-Wawi → F6 → Auftrag wählen → rechte Maustaste → Storno → Stornieren

  • Führen Sie anschließend einen Onlineshop Abgleich durch

Ist der Status des Zahlscheins “Ausstehend“ (pending), dann wird dieser bei Barzahlen (viafintech) invalidiert, ist der Zahlschein allerdings schon “Bezahlt” (paid), dann wird automatisch die Gesamtsumme erstattet. Eine teilweise Rückzahlung ist an der Stelle nicht möglich.

Individualisierung

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

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

Dem Kunden werden nur folgende Fehlermeldungen angezeigt:

Barzahlen steht Ihnen nur in ihrer Landeswährung zur Verfügung.” - Dies ist der Fall, wenn der Kunde auf der Zusammenfassung-Seite versehentlich die Währungsanzeige verstellt hat. In diesem Fall wird er auf die Versand- und Zahlungsart-Seite zurückgeführt. Hier hat er die Möglichkeit entweder eine Zahlungsart passend zur gewünschten Währung auszuwählen oder die Währungsauswahl zu korrigeren. Dann wird Barzahlen auch wieder als Zahlungsart angeboten.

Die Zahlung kann leider nicht ausgeführt werden. Das Tageslimit wäre überschritten.” - In diesem Fall ist ein Fehler bei der Berechnung der Tageslimits aufgetreten. Der verfügbare Betrag des Kunden bei Barzahlen (viafintech) ist geringer als vom Plugin berechnet. Diese sehr unwahrscheinliche Situation kann nur einterten, wenn Sie unterschiedliche Onlineshops an eine Division angebunden haben, dann gilt das Tageslimit für den Kunden in beiden Onlineshops gleichermaßen!

Tritt ein Fehler aufgrung von Limitüberschreitung oder generell in der allgemeinen Kommunikation mit Barzahlen auf, dann wird der Kunde auf die Zahlungsseite zurückgeführt und Barzahlen nicht weiter als mögliche Zahlungsart für die aktuelle Session angeboten.

Im Plugin-Backend werden dem Händler zu jeder Aktion Erfolgs- und Fehlermeldungen angezeigt. Insbesondere werden Fehler in das Shop-Log geschrieben. Die Fehlermeldungen und die allgemeinen Kommunikation mit der Barzahlen API kann dann bequem mit dem Präfix “Barzahlen:“ gefiltert werden.

Im folgende Abschnitt werden die entsprechenden Logtypen und der Umgang mit ihnen genauer erklärt.

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.

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.0.6 (März 2023)

  • Kompatibilität für JTL-Shop 5.2

  • Fix für Probleme beim Webhook-Empfang, wenn FastCGI als PHP-Engine konfiguriert ist

v1.0.5 (Oktober 2022)

  • Update for JTL Shop 5.1.5 und php8

v1.0.4 (Februar 2022)

  • Update for JTL Shop 5.1.0

v1.0.3 (April 2021)

  • Bugfix

v1.0.2 (Februar 2021)

  • Neue Länder Spanien (ES) und Frankreich (FR)

  • Workaround für JTL-Shop 5.0.0 Bug bei Installation von Plugins aus dem Extension Store

  • Verbesserung: Darstellung der Tabelle der Zahlscheine im Adminbereich

v1.0.1 (Januar 2021)

  • Bugfix: HTML Entities werden in API übermittelt

v1.0.0 (Dezember 2020)

  • Initiales Release

Support und Kontakt

siehe Support und Kontakt