Dokumentation Barzahlen Plugin für xt:Commerce 4

Inhalt

1. Installation

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

Entpacken Sie das geladene Archiv in einen Ordner Ihrer Wahl. Der Unterordner src enthält folgende Ordner, die Sie einfach in Ihr Shopsystem laden können:

  • plugins
  • templates
  • xtAdmin

2. Konfiguration

2.1 Modul aktivieren

Loggen Sie sich in den Administrationsbereich Ihres Onlineshops ein und wählen Sie in der seitlichen Menüleiste Inhalte / Plugin / deinstallierte Plugins aus.

Wählen Sie auf der rechten Seite das Barzahlen Plugin aus. Sollte das Plugin nicht auf der ersten Seite der Liste erscheinen, so können Sie am unteren Rand des Bildschirms eine weitere Seite mit Plugins aufrufen.

Klicken Sie auf den Button , welcher sich am Ende der Zeile befindet, und bestätigen Sie die folgende Abfrage mit Ja, um das Plugin zu installieren. Die Installation erfolgt automatisch und endet mit der Ausgabe des Installationsprotokolls.

Schließen Sie den Dialog mit einem Klick auf . Um das Plugin zu aktivieren, wählen Sie im Menü auf der linken Seite den Punkt installiere Plugins, welcher sich direkt über dem Punkt deinstallierte Plugins befindet. Wählen Sie das Barzahlen Plugin aus der Modulklasse payment aus.

Klicken Sie auf den Button um das Plugin zu aktivieren. Bestätigen Sie den Dialog mit Ja. Das Barzahlen Plugin ist nun installiert.

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?page=callback&page_action=zi_barzahlen 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?page=callback&page_action=zi_barzahlen

2.3 Modul konfigurieren

Wählen Sie im linken Menü den Ordner Einstellung und daraus den Unterpunkt Zahlungsweise. Der Status des Plugins ist an dieser Stelle noch inaktiv (rote Kontrollleuchte). Bevor Sie das Zahlungsmodul aktivieren, sollten Sie die Einstellungen an Ihren Shop anpassen.

Klicken Sie dazu auf den Bearbeiten-Button . Es öffnet sich eine Übersicht mit allen verfügbaren Einstellungen. Relevant für die Funktion des Moduls ist der Bereich Main Store.

Geben Sie im oberen Bereich 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. Lassen Sie den Test-Modus vorerst eingeschaltet, um das Modul anschließend testen zu können.

Fahren Sie im unteren Bereich fort, indem Sie dort den verschiedenen Barzahlen Status einen Bestellstatus zuweisen. Die gewählten Status werden Bestellungen automatisch zugewiesen, wenn sich am Status der Barzahlen Transaktion etwas ändert.

Information

Zusätzliche Bestellstatus können Sie unter Einstellungen / Systemstatus / Bestellstatus festlegen. Achten Sie dabei darauf, die Bestellstatus auch für Kunden sowie Admin sichtbar zu machen. Dadurch wird gewährleistet, dass der Auftragsstatus sowohl für Kunden im eigenen Profil, wie auch für Sie selbst angezeigt wird.

Nachdem Sie alle Einstellungen vorgenommen haben, setzten Sie einen Haken hinter Status (oberhalb des Bereichs Main Store) und wählen den Button Speichern. Alternativ können Sie nach dem Speichern das Zahlungsmodul aus der Liste auswählen und über Auswahl aktiveren in Ihren Shop einbinden.

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?page=callback&page_action=zi_barzahlen 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?page=callback&page_action=zi_barzahlen

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

Eine Übersicht aller Barzahlen Transaktionen finden Sie im Administrationsbereich im Untermenü Bestellung / Kunden / Barzahlen.

Hier werden alle Transaktionen mit ID, Bestellnummern, Betrag und Währung aufgeführt. Ferner besteht hier die Möglichkeit nach erfolgter Rücksendung eine Rückzahlung an den Kunden anzustoßen. Außerdem können Sie bei Bedarf Kunden den Zahlschein für eine offene Bestellung mit einem Klick auf das Symbol erneut zusenden. Sofern ein Kunde eine Bestellung storniert, sollten Sie mit einem Klick auf einen ausstehenden Zahlschein ebenfalls stornieren. Die Stornierungsfunktion steht ab Version 1.1.4 zur Verfügung und ist davor über den Händlerbereich (https://partner.barzahlen.de) möglich.

5.2.2 Rückzahlungen anweisen

Rückzahlungen können Sie bequem im Shop-Backend ausführen. Klicken Sie auf in der Zeile der Transaktion, deren (Teil-)Rückzahlung Sie anweisen möchten. Sie gelangen zur Übersicht aller Rückzahlungen, welche die gewünschte Transaktion betreffen.

Um eine neue Rückzahlung hinzuzufügen, wählen Sie und geben den gewünschten Betrag ein. Beachten Sie, dass die Gesamtsumme der einzelnen Rückzahlungsbeträge den Ursprungsbetrag (Warenwert zzgl. Versandkosten) nicht übersteigt.

Speichern Sie Ihre Eingabe und laden Sie die Tabelle mit einem Klick auf neu. Nachdem die Tabelle aktualisiert wurde, erscheint der Rückzahlungsauftrag. Gleichzeitig wird der Status der Bestellung geändert. Bei jeder Statusänderung zur Rückzahlung ändert sich automatisch auch der Status der Bestellung. Auch dieses Mal haben Sie die Möglichkeit, Kunden den Auszahlschein erneut zuzusenden. Klicken Sie dazu auf . Bitte beachten Sie, dass Kunden bereits bei der Anfrage einer Rückzahlung automatisch einen Auszahlschein per E-Mail erhalten.

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

Übertragungsfehler werden vom Modul automatisch im System-Log gespeichert, um die Feststellung und Behebung der Fehlerquelle zu erleichtern. Fehler bei Benachrichtigungen werden im IPN-Log gesichert. Sie können die Fehlerlogs über den Menüpfad System / Logfiles / System-Log bzw. System / Logfiles / IPN-Log aufrufen.

Im Hauptfenster öffnet sich eine Liste mit allen Fehlermeldungen. Jeder Eintrag enthält Informationen zum Zeitpunkt des Fehlers, Name des betroffenen Moduls und eine Identifikationsnummer. Bei Fehlern während der Bestellung wird für ID die Bestellnummer eingetragen. Sofern eine Rückzahlung nicht möglich war, trägt das System die Identifikationsnummer der Transaktion, von welcher eine Rückzahlung erfolgen sollte, ein.

Klicken Sie auf um nähere Informationen zu einer Fehlermeldung zu erhalten.

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 linken Menü Einstellungen / Zahlungsweise.

Wählen Sie Barzahlen aus und klicken anschließend auf . Damit gehen Ihre Einstellungen nicht verloren und Sie können das Zahlungsmodul jederzeit wieder mit wenigen Klicks aktivieren.

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.

Falls Sie Barzahlen deinstallieren möchten, wählen Sie an gleicher Stelle (Einstellungen / Zahlungsweise) oder unter Inhalte / Plugin / installierte Plugins auf und bestätigen Sie die Sicherheitsabfrage. Das Plugin wird dadurch automatisch deinstalliert. Bitte beachten Sie, dass eine Deinstallation zum Verlust der getätigten Einstellungen führt.

7.3 Komplett löschen

Um das Modul vollständig aus ihrem Shop zu löschen, führen Sie zuerst eine Deinstallation durch. Danach löschen Sie den Unterordner zi_barzahlen aus dem Ordner /plugins sowie die Datei zi.resend.php aus dem Ordner /xtAdmin.

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 eine aktuellere Version des Plugins zu installieren, ist es notwendig, die alte Version zu deinstallieren. Wählen Sie im seitlichen Menü Inhalte / Plugin / installierte Plugins und klicken Sie im Anschluss in der Zeile mit dem Barzahlen Modul auf und bestätigen Sie die Sicherheitsabfrage. Das Plugin wird dadurch automatisch deinstalliert. Laden Sie sich anschließend die neuste Version des Plugins herunter und führen Sie eine Installation und Konfiguration wie oben beschrieben durch. Ihre Transaktionen mitsamt der Rückzahlungen bleiben erhalten.

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.