Dokumentation Barzahlen Plugin für Magento

Inhalt

1. Installation

1.1 Installation via Magento Connect

Information

Magento unter Version 1.5 benötigt Connect 1.0 Extensions
Magento ab Version 1.5 benötigt Connect 2.0 Extensions

Öffnen Sie im Admin Panel den Magento Connect Manager. Diesen finden Sie unter System / Magento Connect. Zur Sicherheit werden Sie aufgefordert, erneut Ihren Nutzernamen sowie das Passwort einzugeben.

1.1.1 Automatische Installation

Öffnen Sie auf der Magento Connect Webseite die Pluginseite für Barzahlen (http://www.magentocommerce.com/magento-connect/barzahlen-1.html) und lassen sie sich den Extension Key für Ihre Magento Version generieren. Fügen Sie diesen anschließen im Magento Connect Manager ein und klicken Sie auf Install.

Der Connect Manager ermittelt, ob noch andere Erweiterungen benötigt werden. Da dies nicht der Fall ist, wird nur das Barzahlen Paket angezeigt, welches Sie mit einem Klick auf Proceed installieren. Kehren Sie nach erfolgreicher Installation in den Administrationsbereich zurück, um das Zahlungsmodul zu konfigurieren.

1.1.2 Heruntergeladenes Plugin

Sofern Sie das Plugin noch nicht heruntergeladen haben, können Sie dies im Integrationsbereich von Barzahlen (https://integration.barzahlen.de/de/shopsysteme/magento) tun.

Wählen Sie im Bereich Direct package file upload über Durchsuchen das heruntergeladene Paket aus und klicken Sie anschließend auf Upload. Das Modul wird anschließend automatisch in Ihren Shop geladen und installiert. Kehren Sie nach erfolgreicher Installation in den Administrationsbereich zurück, um das Zahlungsmodul zu konfigurieren.

Information

Sollten Sie nach der Installation Probleme haben, Shop oder Admin Panel zu erreichen, prüfen Sie, ob in Ihrem Shop-Verzeichnis die Datei maintenance.flag vorhanden ist und löschen Sie diese gegebenenfalls. Die Datei verhindert den Zugriff auf den Shop, während Erweiterungen geladen oder geändert werden.

1.2 Manuelles Einfügen in das Dateisystem

Laden Sie sich im Integrationsbereich von Barzahlen (https://integration.barzahlen.de/de/shopsysteme/magento) das Zahlungsmodul für Magento herunter. Entpacken Sie das geladene Archiv in einen Ordner Ihrer Wahl.

Fügen Sie den Unterordner app auf Ihrem Webserver in den Ordner Ihres Shopsystems, welcher die gleiche Unterordner-Struktur enthält, ein. Dadurch werden die notwendigen Dateien zum System hinzugefügt.

2. Konfiguration

2.1 Anmeldung Partnerbereich

Sofern Sie sich bisher noch nicht im Barzahlen-Partnerbereich (https://controlcenter.barzahlen.de/) registriert haben, holen Sie dies bitte nun nach. Nachdem Sie das Registrierungsformular ausgefüllt und Ihre E-Mailadresse durch Klick auf den Bestätigungslink verifiziert haben, loggen Sie sich ein. Wählen Sie den Menüpunkt Einstellungen und dort den Unterpunkt Divisionen.

Auf dieser Seite finden Sie Division ID, API-Schlüssel sowie Benachrichtigungsschlüssel. Weiterhin können Sie an dieser Stelle die Benachrichtigungs-URL für Ihren Shop einstellen, um Statusänderungen bezüglich Transaktionen und Rückzahlungen an das Zahlungsmodul zu senden, damit diese automatisch in Ihren Shop eingetragen werden.

Information

Die Callback-Klasse, welche Benachrichtigungen verarbeitet, wird durch den URL-Zusatz index.php/barzahlen/ipn aufgerufen. Angenommen ihre Shop-URL wäre https://www.beispiel-shop.de/, dann tragen Sie im Feld Benachrichtigungs-URL folgendes ein, um Benachrichtigungen zu erhalten: https://www.beispiel-shop.de/index.php/barzahlen/ipn

2.2 Modul konfigurieren

Wählen Sie in der oberen Menüleiste den Punkt System und daraus den Unterpunkt Konfiguration. Klicken Sie anschließend im Menü auf der linken Seite auf Zahlarten im Bereich Verkäufe.

Geben Sie die Daten für Shop ID, Zahlungsschüssel und Benachrichtigungsschlüssel, welche Sie nach Ihrer Registrierung im Händlerbereich (https://controlcenter.barzahlen.de/) erhalten bzw. via E-Mail zugesandt bekommen haben, ein. Lassen Sie den Test-Modus vorerst eingeschaltet, um das Modul anschließend testen zu können.

Derzeit sind nur Zahlungen aus Deutschland bis zu einem Gesamtbetrag (Warenwert zzgl. Versandkosten) unter 1000 € möglich. Diese Einstellungen sind als Standard bereits gesetzt.

Weiterhin können Sie festlegen, an welcher Stelle Barzahlen in der Auflistung der Bezahlmethoden aufgeführt sein soll und ob Sie durch den Debug-Modus zusätzliche Daten loggen möchten. Stellen Sie sicher, dass das Zahlungsmodul aktiviert ist. Nachdem Sie alle Einstellungen vorgenommen haben, wählen Sie den Button oben rechts.

3. Testbestellung durchführen

3.1 Ausgeschlossene Bestellungen

Prüfen Sie, ob die Ausschlusskriterien des Zahlungsplugins korrekt eingestellt sind, indem Sie nacheinander folgende Einkaufsszenarien durchlaufen:

  • Bestellung mit Warenwert größer / gleich 1.000 Euro
  • Bestellung mit einer Kundenadresse außerhalb Deutschlands

Dabei sollte Barzahlen nicht in der Zahlungsauswahl auftauchen, da bei jeder dieser Bedingungen die Zahlscheinanfrage an die Barzahlen-API fehlschlagen würde und der Kunde mit Fehlermeldung zurück zur Zahlungsauswahl geleitet wird. An dieser Stelle gilt es Ärger beim Kunden und einen eventuellen Kaufabbruch zu verhindern.

3.2 Testbestellung

Legen Sie in der Folge einen beliebiges Produkt (Warenwert kleiner 1.000 Euro) in den Warenkorb und gehen Sie zur Kasse. Bestätigen Sie Lieferadresse (innerhalb von Deutschland) sowie Versandart und gehen Sie zum Schritt Zahlungsweise wählen über. Wählen Sie Barzahlen aus der Auswahlliste und fahren Sie mit dem Bestellvorgang fort. Unter dem Erklärungstext werden die Logos unserer Partner angezeigt, wie in der nachfolgenden Grafik vereinfacht dargestellt.



Mit Abschluss der Bestellung bekommen Sie einen Zahlschein angezeigt, den Sie sich ausdrucken oder auf Ihr Handy schicken lassen können. Bezahlen Sie den Online-Einkauf mit Hilfe des Zahlscheins an der Kasse einer Barzahlen-Partnerfiliale.

Bezahlen Sie bei:

Information

Einkäufe, die mit Barzahlen im Testmodus durchgeführt werden, erhalten eine Transaktionsnummer sowie einen Barcode vom Barzahlen Server zugewiesen. Die übermittelten Daten werden nur temporär zu Testzwecken gespeichert. Getätigte Testeinkäufe können später bedenkenlos im eigenen System storniert werden.

Bestätigen Sie Ihre getätigten Angaben, um den Bestellvorgang abzuschließen.

Information

Bitte beachten Sie, dass die SMS-Funktion im Testmodus nicht zur Verfügung steht und dass an den Testkunden keine zusätzliche E-Mail mit dem Zahlschein versendet wird. Weiterhin sind auf dem Zahlschein nicht die nächsten drei Partnerfilialen aufgelistet. Alle Funktionen stehen automatisch im Live-Betrieb bereit.

3.3 Zahlung simulieren

Loggen Sie sich in den Händlerbereich von Barzahlen (https://controlcenter.barzahlen.de/) ein und wechseln sie im Reiter Transaktionen auf den Bereich Sandbox-Transaktionen.

Sie sehen eine Liste aller Sandbox-Transaktionen, welche Sie über ihr Shopsystem testweise getätigt haben. In der rechten Seite haben Sie die Möglichkeit, die Transaktionen mit als bezahlt zu markieren. Ein Klick auf simuliert einen Ablauf der Frist für die Zahlung einer Barzahlen Transaktion und ein Klick auf storniert eine Transaktion.

Bezahlen Sie probeweise eine Transaktion ihrer Wahl. Der Status der Transaktion ändert sich auf bezahlt und sofern die Sandbox-Benachrichtigungs-URL korrekt gesetzt ist, ändert sich der Status der Bestellung in Ihrem System.

Information

Die Callback-Klasse, welche Benachrichtigungen verarbeitet, wird durch den URL-Zusatz index.php/barzahlen/ipn aufgerufen. Angenommen ihre Shop-URL wäre https://www.beispiel-shop.de/, dann tragen Sie im Feld Benachrichtigungs-URL folgendes ein, um Benachrichtigungen zu erhalten: https://www.beispiel-shop.de/index.php/barzahlen/ipn

4. Shop anpassen

Neben der eigentlichen Integration des Zahlungsplugins gibt es weitere Details, die nach der erfolgreichen Einbindung bedacht werden sollten, um einen reibungslosen Ablauf zu gewährleisten.

4.1 AGB und Datenschutz

Erweiteren Sie ihre allgemeinen Geschäftsbedingungen sowie Datenschutzhinweise um Passagen die Barzahlen als Zahlungsanbieter betreffen. Sie finden vorgefertigete Texte hier: AGB & Datenschutz

4.2 Logos

Sofern Sie Logos von Zahlungsanbietern in der Fußzeile Ihres Online-Shops oder auf der Startseite nutzen, damit Kunden auf den ersten Blick sehen, wie man bei Ihnen den Einkauf bezahlen kann, finden Sie hier Logos um auf Barzahlen als angebotene Zahlungsmethode aufmerksam zu machen: Logos

4.3 Zahlungsbeschreibung

Viele Online-Shops stellen eine zusätzliche Informationsseite bereit auf welcher sich Kunden über die angebotenen Versand- und Zahlungsarten detailiert informieren können. Unter Textvorlagen haben wir Texte in unterschiedlicher Länge für Sie vorbereitet.

4.4 E-Mails

Auch in der Bestätigungsmail sollte die verwendete Zahlungsart neben den bestellten Waren bzw. Dienstleistungen noch einmal aufgeführt werden. Achten Sie darauf, dass Ihr E-Mail-Template keine Überweisungsaufforderung oder ähnliches enthält, um Kunden nach dem Kauf nicht zu verunsichern. Ein Beispiel für eine ausführliche Zahlungsartbeschreibung in der Bestätigunsmail finden Sie unter Textvorlagen.

4.5 Werbemittel

Zusätzliche Werbemittel für Newsletter, Blogs oder Ankündigungen in Ihrem Online-Shop finden Sie unter Banner.

5. Livebetrieb

5.1 Umschalten auf Livebetrieb

Damit Bestellungen über Barzahlen abgerechnet werden können, öffenen Sie im Administrationsbereich Ihres Online-Shops erneut die Konfiguration für das Barzahlen-Zahlungsmodul. Deaktivieren Sie anschließend den Testmodus.

Sichern Sie die Einstellung anschließend mit einem Klick auf Aktualisieren. Dadurch werden alle Anfragen an die produktive API gesendet, welche die übertragenen Daten sichert und die Zahlungsabwicklung gewährleistet.

5.2 Zahlungen verwalten

Der Kunde bekommt den Zahlschein direkt nach dem Bestellvorgang angezeigt und erhält gleichzeitig eine E-Mail von Barzahlen, an welche das PDF-Dokument ebenfalls angehängt ist. Sollte Ihr Kunde dennoch erneut den Zahlschein benötigen, können Sie einen erneuten Versand in der Bestellübersicht veranlassen. Rufen Sie zuerst die Liste aller Bestellungen über Verkäufe / Bestellungen in der Hauptmenüleiste auf. Wählen Sie in der Zeile der betroffenen Bestellung Ansehen.

Sofern der Zahlschein noch nicht bei einem unserer Einzelhandelspartner beglichen wurde, können Sie mit einem Klick auf den Zahlschein erneut zusenden.

5.2.1 ausstehend

Jede neue Bestellung wird im Status unbezahlt angelegt. Der Kunde erhält nach dem Abschluss des Bestellvorgangs einen Zahlschein, welchen er bei einem Offline-Partner bezahlen kann.

5.2.2 bezahlt

Sobald der Zahlschein beim stationären Partner gescannt und bezahlt wurde, kontaktiert Barzahlen den integrierten IPN-Controller des Zahlungsmoduls, sofern Sie eine Benachrichtigungs-URL im Händlerbereich eingegeben haben.

Die Benachrichtigung wird validiert und bei erfolgreichem Abgleich wird die Bestellung mit dem Status bezahlt versehen. Die bestellte Ware ist bezahlt und kann versendet werden.

5.2.3 abgelaufen

Bezahlt der Kunde die Bestellung mithilfe des Zahlscheins nicht innerhalb der vorgegebenen Zeitspanne, erhält das Zahlungsmodul eine entsprechende Benachrichtigung. Der Bestellstatus wird automatisch auf Status abgelaufen gesetzt.

5.2.4 Zahlschein stornieren

Wenn ein Kunde sich umentscheidet und noch vor Ablauf der Zahlungsfrist die Bestellung storniert oder Sie eine Fake-Bestellung ausmachen, sollten Sie den Zahlschein im Control Center (https://controlcenter.barzahlen.de) stornieren.

Ab Version 1.1.9 des Barzahlen-Moduls für Magento (ab Version 1.5.1.0) wird der Zahlschein automatisch storniert, wenn Sie eine Bestellung im Magento Administrationsbereich stornieren.

6. Fehlerbehandlung

6.1 Übertragungsfehler bei der Bestellung

Bei einer Bestellabwicklung startet das Barzahlen Modul bei einer fehlerhaften oder keiner Rückmeldung vom Server einen zweiten Versuch. Sofern auch der zweite Versuch nicht erfolgreich ist, wird der Kunde zurück zur Auswahl der Zahlungsweise geleitet und kann dort eine Alternative auswählen, um die Bestellung abzuschließen.

Der Grund für den Fehler wird in diesem Fall im Fehler-Log hinterlegt und liefert Ihnen später Aufschluss über die Ursache.

6.2 Error-Logging

Alle aufgetretenen Fehler werden vom Modul automatisch zusammen mit Zeitpunkt und relevanten Daten in die Fehlerdatei barzahlen.log gespeichert. Sie finden diese im Unterordner /var/log/barzahlen.log.

6.3 Erste Hilfe

In der folgenden Tabelle finden Sie Fehlermeldungen, die Sie unter Umständen selbst sehr schnell und einfach beheben können.

"bad request" Wahrscheinlich verwenden Sie eine alte Version des Plugins. Aktualisieren Sie auf die letzte verfügbare Version und testen Sie das Plugin erneut.
"shop not found" Der Barzahlen Server hat die angegebene Shop ID nicht zuordnen können. Bitte überprüfen Sie die eingetragene Shop ID.
"hash not recognized"
oder
"hash comparison failed"
Der gesendete Hash konnte nicht verifiziert werden. Bitte überprüfen Sie die eingetragene Shop ID sowie den Zahlungsschlüssel mit den Daten, die Sie im Control Center finden. (https://controlcenter.barzahlen.de)
"transaction not found"
oder
"refund not found"
oder
"order not found"
Sie erhalten eine dieser Fehlermeldungen, wenn beim Bearbeiten einer Benachrichtigung die Bestellung, die Transaktion oder die Rückzahlung nicht im System gefunden wurde. Stellen Sie sicher, dass Sie den gesuchten Eintrag nicht bereits entfernt haben.
"Warning: error_log(...) failed to open stream: Permission denied" Die notwendigen Dateiberechtigungen für das Log-Verzeichnis sind nicht korrekt (777) gesetzt. Beheben Sie das Problem, wie im Abschnitt Einstellungen auf dem Webserver im Kapitel Vorbereitung beschrieben.

Sollten Sie andere Fehlermeldungen erhalten oder sollten die vorgeschlagenen Lösungsschritte keine Abhilfe schaffen, zögern Sie nicht, den Support zu kontaktieren.

7. Deinstallation

7.1 Temporär deaktivieren

Sollten Sie das Barzahlen Modul nur vorübergehend deaktivieren wollen, rufen Sie die Konfiguration über System / Konfiguration in der oberen Menüleiste auf und klicken Sie im Menü auf der linken Seite auf Zahlarten. Wählen Sie anschließend Barzahlen und selektieren Sie für das Feld Aktiviert aus dem Drop-Down-Menü Nein.

Speichern Sie Ihre Eingabe mit einem Klick auf . Diese Schaltfläche befindet sich oben rechts. Das Zahlungsmodul von Barzahlen ist somit nicht mehr für Ihre Kunden verfügbar, Ihre persönlichen Händlerdaten bleiben aber für eine später Reaktivierung gespeichert.

7.2 Deinstallieren

Information

Bitte beachten Sie, dass Sie nach erfolgter Deinstallation des Moduls keine Statusänderungen zu offenen Transaktionen erhalten. Diese sind jedoch jederzeit im Händlerbereich (https://partner.barzahlen.de) aufrufbar.

Sofern Sie das Barzahlen Modul über den Magento Connect Manager installiert haben, können Sie auch die Deinstallation auf diesem Wege durchführen. Rufen Sie den Magento Connect Manager über System / Magento Connect / Mangento Connect Manager in der oberen Menüleiste auf. Geben Sie Nutzernamen sowie Passwort ein.

Im unteren Bereich sehen Sie alle installierten Erweiterungen. Wählen Sie in der Spalte Actions die Option Uninstall und klicken Sie anschließend auf Commit Changes. Das Modul wird nun automatisch entfernt.

Falls Sie das Zahlungsmodul manuell installiert haben, müssen Sie folgende Ordner und Dateien ebenfalls manuell von Ihrem Webserver löschen, um das Modul vollständig zu deinstallieren:

  • /app/code/community/ZerebroInternet/
  • /app/design/adminhtml/default/default/template/barzahlen/
  • /app/design/frontend/base/default/layout/barzahlen.xml
  • /app/design/frontend/base/default/template/barzahlen/
  • /app/etc/modules/ZerebroInternet_Barzahlen.xml
  • /app/locale/de_DE/ZerebroInternet_Barzahlen_Admin.csv
  • /app/locale/de_DE/ZerebroInternet_Barzahlen_Frontend.csv
  • /app/locale/en_US/ZerebroInternet_Barzahlen_Admin.csv
  • /app/locale/en_US/ZerebroInternet_Barzahlen_Frontend.csv
  • /var/log/barzahlen.log

8. Plugin Update

Information

Ab Version 1.2.0 des Barzahlen Plugins werden Sie in wöchentlichen Abständen über Updates automatisch nach dem Login in den Administrationsbereich informiert.

Um das Plugin auf die neuste Version zu aktualisieren, laden Sie sich zuerst die aktuelle Version des Barzahlen-Zahlungsmoduls herunter. Öffnen Sie im Admin Panel den Magento Connect Manager. Diesen finden Sie unter System / Magento Connect. Zur Sicherheit werden Sie aufgefordert, erneut Ihren Nutzernamen sowie das Passwort einzugeben.

Im unteren Bereich sehen Sie alle installierten Erweiterungen mitsamt ihrer Versionsnummer.

Automatisch Installation

Klicken Sie auf den Button , welcher sich auf der rechten Seite der Titelzeile über den aufgelisteten Erweiterungen befindet. Der Magento Connect Manager prüft nun alle Erweiterungen auf Updates. Wählen Sie anschließend die aktuellste Pluginversion aus und bestätigen Sie Ihre Auswahl mit einem Klick auf Commit Changes.

Heruntergeladenes Plugin

Wählen Sie in der Spalte Actions die Option Uninstall und klicken Sie anschließend auf Commit Changes. Das Modul wird nun automatisch entfernt.


Wählen Sie danach im Bereich Direct package file upload über Durchsuchen das neue, heruntergeladene Paket aus und klicken Sie anschließend auf Upload. Das Modul wird anschließend automatisch in Ihren Shop geladen und installiert. Kehren Sie nach erfolgreicher Installation in den Administrationsbereich zurück.


Information

Sofern Sie das Modul manuell installiert haben, entpacken Sie das heruntergeladene Archiv und fügen den Inhalt in das Shopverzeichnis ihres Webservers ein. Bestätigen Sie dazu das Überschreiben der alten Dateien. Löschen Sie anschließend den Cache über das Admin-Menü (System/Cache-Verwaltung).

8.1 Update auf Version 1.1.0+

Wählen Sie in der oberen Menüleiste den Punkt System und daraus den Unterpunkt Konfiguration. Klicken Sie anschließend im Menü auf der linken Seite auf Zahlarten im Bereich Verkäufe.

Reduzieren Sie gegebenfalls den Maximalbetrag auf unter 1.000 Euro.


Wählen Sie den Button oben rechts.

9. Support

Das Team von Barzahlen steht Ihnen bei jeglichen Fragen gern zur Verfügung.

Sie können uns eine E-Mail an support@barzahlen.de senden oder das Kontaktformular verwenden. Ihre E-Mail wird daraufhin in unserem Ticket-System direkt dem zuständigen Mitarbeiter zugeordnet und bearbeitet.