Dokumentation Barzahlen Plugin für OXID 4.5

Information

Das Zahlungsmodul ist nicht mit der Version 4.5.0 kompatibel.

Inhalt

1. Installation

1.1 Download

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

1.2 Einfügen in das Dateisystem

Entpacken Sie das geladene Archiv in einen Ordner Ihrer Wahl. Sie finden folgende, für OXID-Module übliche, Ordnerstruktur im Unterordner src vor:

  • admin
  • modules
  • out
  • views

1.3 Anpassungen für die Datenbank

Loggen Sie sich in den Administrationsbereich Ihres Shopsystems ein und wählen Sie im Menü den Punkt Service / Tools.

Wählen Sie den Button Durchsuchen und öffnen Sie die im Installationspaket enthaltende Datei install.sql. Klicken Sie anschließend auf Update starten.

Information

Sollten Sie OXID Enterprise Edition 4.5.1 - 4.5.12 verwenden, nutzen Sie bitte die Datei install_ee.sql. Öffnen Sie die Datei vor dem Update und vervielfälltigen Sie den zweiten Block in Anhängigkeit der vorhandenen Shops. Dies könnte wie folgt aussehen:

INSERT INTO `oxtplblocks` (`OXID`, `OXACTIVE`, `OXSHOPID`, `OXTEMPLATE`, `OXBLOCKNAME`, `OXPOS`, `OXFILE`, `OXMODULE`) VALUES
('barzahlen_select_payment_1', 1, 1, 'page/checkout/payment.tpl', 'select_payment', 1, 'page/checkout/payment/select_payment', 'barzahlen'),
('barzahlen_payment_error_1', 1, 1, 'page/checkout/payment.tpl', 'checkout_payment_errors', 1, 'page/checkout/payment/checkout_payment_errors', 'barzahlen'),
('barzahlen_thankyou_1', 1, 1, 'page/checkout/thankyou.tpl', 'checkout_thankyou_info', 1, 'page/checkout/thankyou/checkout_thankyou_info', 'barzahlen');

INSERT INTO `oxtplblocks` (`OXID`, `OXACTIVE`, `OXSHOPID`, `OXTEMPLATE`, `OXBLOCKNAME`, `OXPOS`, `OXFILE`, `OXMODULE`) VALUES
('barzahlen_select_payment_2', 1, 2, 'page/checkout/payment.tpl', 'select_payment', 1, 'page/checkout/payment/select_payment', 'barzahlen'),
('barzahlen_payment_error_2', 1, 2, 'page/checkout/payment.tpl', 'checkout_payment_errors', 1, 'page/checkout/payment/checkout_payment_errors', 'barzahlen'),
('barzahlen_thankyou_2', 1, 2, 'page/checkout/thankyou.tpl', 'checkout_thankyou_info', 1, 'page/checkout/thankyou/checkout_thankyou_info', 'barzahlen');

2. Konfiguration

2.1 Modul aktivieren

Öffnen Sie über das Administrationsmenü den Bereich Stammdaten / Grundeinstellungen.

Wählen Sie den Reiter System und dort den Bereich Module. Fügen Sie den Inhalt der Datei extends.txt zu den bestehenden Inhalten.

payment => barzahlen/views/barzahlen_payment
thankyou => barzahlen/views/barzahlen_thankyou
oxpaymentgateway => barzahlen/core/barzahlen_payment_gateway
oxorder => barzahlen/core/barzahlen_order
navigation => barzahlen/core/barzahlen_navigation

Sofern Sie bereits eine oder mehrere der aufgeführten Komponenten durch andere Module erweitern, ist es notwendig, diese durch kaufmännische Und-Zeichen (&) zu trennen.

Beispiel:
payment => barzahlen/views/barzahlen_payment&anderesModul/views/andererView

Nachdem Sie Ihre Einstellungen gespeichert haben, sollten Sie den /tmp Ordner Ihres Shop leeren und den Administrationsbereich neu aufrufen. Dadurch werden die getätigten Änderungen sichtbar.

2.2 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?cl=barzahlen_callback 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?cl=barzahlen_callback

2.3 Modul konfigurieren

Wählen Sie den moduleigenen Menüpunkt Barzahlen / Einstellungen.

Geben Sie die Daten für Shop-ID, Zahlungsschüssel und Benachrichtigungsschlüssel, welche Sie nach Ihrer Registrierung im Händlerbereich (https://partner.barzahlen.de) erhalten bzw. via E-Mail zugesandt bekommen haben, ein. Aktivieren Sie den Sandbox Modus um das Zahlungsmodul vorerst zu testen. Schalten Sie das Debugging ein, sofern sie neben Fehlermeldungen auch die einzelnen Verbindungen geloggt haben möchten. Sichern Sie Ihre Eingaben mit einem Klick auf Speichern.

Öffnen Sie den Bereich Shopeinstellungen und wählen Sie den Unterpunkt Zahlungsarten. Wählen Sie anschließend Barzahlen aus der Liste der verfügbaren Zahlungsarten aus. Die grundlegenden Einstellungen für den Bereich Stamm sind bereits getätigt. So können mit Barzahlen nur Einkäufe unter 1.000 Euro abgewickelt werden.

Sollten Sie Barzahlen für einen anderen Maximalwert anbieten wollen, tragen Sie diesen ein und bestätigen anschließend mit dem Button Speichern.

Klicken Sie auf den Button und wählen Sie anschließend die Kundengruppen, denen Sie die Zahlung mit Barzahlen ermöglichen wollen, via Drag-and-Drop aus.

Wählen Sie danach den Reiter Länder und klicken Sie auf den Button . Bewegen Sie Deutschland auf die rechte Seite, zu den zugeordneten Ländern.

Weisen Sie als nächstes die Zahlungsart Barzahlen den gewünschten Versandarten zu. Klicken Sie dazu auf Shopeinstellungen / Versandarten im Administrationsmenü.

Wählen Sie nacheinander alle Versandarten aus, die zusammen mit Barzahlen angeboten werden sollen. Selektieren Sie dazu die gewünschte Versandart in der Liste und öffnen sie den Reiter Zahlungsarten. Klicken Sie dann auf den Button . Ziehen Sie anschließend Barzahlen auf die rechte Seite.

Das Zahlungsmodul ist nun eingerichtet und einsatzbereit.

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?cl=barzahlen_callback 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?cl=barzahlen_callback

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

5.2.1 Übersicht

Navigieren Sie zur Bestellübersicht im Shop-Backend (Bestellungen verwalten / Bestellungen). Wählen Sie die Bestellung, die Sie interessiert. Das Barzahlen Modul erweitert die Bestellansicht um einen Reiter, über welchen alle Informationen zum aktuellen Status von Transaktionen abgerufen werden können. Sofern Ihr Kunde nochmals den Zahlschein benötigt, können Sie einen erneuten Versand an die angegebene E-Mail-Adresse über den Button veranlassen.

5.2.2 Zahlschein stornieren

Ab Plugin-Version 1.1.4 wird bei Löschung oder Stornierung einer Bestellung im OXID-Administrationsbereich wird der zugehörige ausstehende Zahlschein automatisch storniert. Sofern die Bestellung nur storniert wird und damit im System verbleibt wird eine erfolgreiche parallele Stornierung des Zahlscheins im Status angezeigt.

Vor früheren Version des Barzahlen Plugins ist es notwendig den Zahlschein nach Stornierung der Bestellung im Händlerbereich (https://partner.barzahlen.de) zu stornieren.

5.2.3 Rückzahlungen anweisen

Rückzahlungen können Sie bequem im Shop-Backend ausführen. Sobald eine Bestellung bezahlt wurde, erscheint in der Übersicht eine Tabelle mit Rückzahlungsinformationen. Geben Sie einfach den gewünschten Betrag ein und bestätigen Sie mit Klick auf speichern. Der maximal zulässige Betrag wird rechts angezeigt. Dieser ergibt sich aus dem Ursprungsbetrag abzüglich ausstehender und abgeschlossener Rückzahlungen.

Nachdem die Rückzahlung erfolgreich von Barzahlen entgegengenommen wurde, erhalten Sie eine Bestätigung und der Betrag taucht in der Übersicht auf. Auch hier haben Sie die Möglichkeit, den Auszahlschein bei Bedarf erneut zuzusenden.


Wie die oben aufgeführte Erfolgsmeldung, teilt Ihnen das System bei jeder Eingabe das Ergebnis mit.

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

Um das Barzahlen Plugin lediglich temporär als Zahlungsweise zu deaktivieren, wählen Sie im Administrations-Menü Shopeinstellungen / Zahlungsarten. Wählen Sie anschließend das Barzahlen Modul aus der Liste aus und deselektieren Sie die Checkbox Aktiv.

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.

Deaktivieren Sie das Module wie oben beschrieben und löschen Sie anschließend die Dateien, die Sie während der Vorbereitung in das Shopsystem eingefügt haben.

  • /admin/barzahlen_settings.php
  • /admin/barzahlen_transactions.php
  • /log/barzahlen.log
  • /modules/barzahlen/
  • /out/admin/de/barzahlen_lang.php
  • /out/admin/en/barzahlen_lang.php
  • /out/admin/tpl/barzahlen_settings.tpl
  • /out/admin/tpl/barzahlen_transactions.tpl
  • /out/[ihr_template]/de/barzahlen_lang.php
  • /out/[ihr_template]/en/barzahlen_lang.php
  • /views/barzahlen_callback.php

8. Plugin Update

Information

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

Um das Zahlungsmodul von Barzahlen auf eine neue Version zu aktualisieren, gehen Sie wie folgt vor: Laden Sie sich das aktuelle Plugin für ihre OXID Version von der Webseite und überschreiben Sie einfach die vorhandenen Moduldateien.

Loggen Sie sich in den Administrationsbereich ihres Shopsystems ein und wählen Sie im Menü den Punkt Service / Tools.

Wählen Sie den Button Durchsuchen und öffnen Sie die im Installationspaket enthaltende Datei update.sql. Klicken Sie anschließend auf Update starten.

Öffnen Sie anschließend im Bereich Barzahlen / Einstellungen und geben Sie Ihre Shop ID sowie Zahlungs- und Benachrichtigungsschlüssel erneut ein. Leeren Sie abschließend den Ordner /tmp in Ihrem Shopverzeichnis und laden Sie anschließend den Administrationsbereich neu.

8.1 Update auf Version 1.1.0+

Öffnen Sie im Shopbackend den Bereich Shopeinstellungen und wählen Sie den Unterpunkt Zahlungsarten. Wählen Sie anschließend Barzahlen aus der Liste der verfügbaren Zahlungsarten aus.

Reduzieren Sie den Maximalwert auf höchstens 999.99 Euro und bestätigen anschließend mit dem Button Speichern.

8.2 Update auf Version 1.1.4+

Öffnen Sie über das Administrationsmenü den Bereich Stammdaten / Grundeinstellungen.

Wählen Sie den Reiter System und dort den Bereich Module. Ergänzen Sie ggf. die installierten Moduldetails.

payment => barzahlen/views/barzahlen_payment
thankyou => barzahlen/views/barzahlen_thankyou
oxpaymentgateway => barzahlen/core/barzahlen_payment_gateway
oxorder => barzahlen/core/barzahlen_order
navigation => barzahlen/core/barzahlen_navigation

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.