Zahlungsgebühren (dfpaymentfees) — Vollständige Anleitung

Überblick

Mit DataFirefly Zahlungsgebühren weisen Sie jeder Zahlungsart in Ihrem PrestaShop-8- oder -9-Shop zusätzliche Gebühren zu. Das Ziel ist zweifach: die realen Kosten einer Zahlungsart weitergeben (Kartenprovisionen, Abwicklung der Nachnahme, Bearbeitung von Schecks oder Überweisungen) und Ihre Kunden zu den für Ihren Shop vorteilhaftesten Zahlungsarten lenken.

Das Modul basiert auf einer Regel-Engine: Jede Regel kombiniert einen Festbetrag und/oder einen Prozentsatz, eine Berechnungsbasis, Grenzen, eine Gratis-Schwelle und eine Reihe von Bedingungen (Kundengruppe, Land, Währung, Warenkorbsumme). Die Gebühren werden dem Kunden während des Checkouts angezeigt und anschließend bei der Validierung automatisch zur Bestellung hinzugefügt.

Installation

1. Gehen Sie im PrestaShop-Backoffice zu Module → Modulmanager → Modul hochladen.
2. Wählen Sie die Datei dfpaymentfees.zip aus, die Sie aus Ihrem DataFirefly-Konto heruntergeladen haben.
3. Klicken Sie auf Installieren und anschließend auf Konfigurieren.
4. Leeren Sie den PrestaShop-Cache (Erweiterte Einstellungen → Leistung → Cache leeren).
5. Klicken Sie auf der Konfigurationsseite auf Gebührenregeln verwalten, um Ihre erste Regel anzulegen.

Allgemeine Einstellungen

Die Konfigurationsseite des Moduls (Module → Modulmanager → Zahlungsgebühren → Konfigurieren) enthält zwei globale Einstellungen:

• Gebühren im Checkout anzeigen — zeigt den Gebührenbetrag während der Bestellung neben jeder Zahlungsart an. Deaktivieren Sie diese Option, wenn Sie die Gebühren erst bei der Validierung anwenden möchten, ohne sie in der Liste der Zahlungsarten anzukündigen.
• Gebühren-Label — Standard-Label, das dem Kunden und auf der Bestellung angezeigt wird (zum Beispiel „Zahlungsgebühr“). Dieses Feld ist mehrsprachig und kann pro Regel überschrieben werden.

Eine Gebührenregel anlegen

Klicken Sie unter Gebührenregeln verwalten auf Gebührenregel hinzufügen. Das Formular ist in vier Blöcke gegliedert: Identifikation, Betrag, Grenzen und Bedingungen.

Identifikation

• Aktiv — aktiviert oder deaktiviert die Regel, ohne sie zu löschen.
• Label (Kunde) — der Text, der dem Kunden im Checkout und auf der Bestellung angezeigt wird. Mehrsprachig und Pflichtfeld.
• Zahlungsart — das betroffene Modul (zum Beispiel ps_wirepayment, ps_checkpayment, Ihr Kartenzahlungsmodul…) oder Alle Zahlungsarten für eine generische Regel.
• Priorität — eine ganze Zahl. Ein niedrigerer Wert wird zuerst ausgewertet. Siehe „Auswertungsreihenfolge“ weiter unten.

Gebührenbetrag

• Feste Gebühr — ein hinzugefügter Festbetrag (zum Beispiel 1.50).
• Prozentuale Gebühr — ein Prozentsatz, der auf die Berechnungsbasis angewendet wird (zum Beispiel 2.5 für 2,5 %).
• Versandkosten in die %-Basis einbeziehen — wenn aktiviert, gilt der Prozentsatz für Produkte und Versandkosten; andernfalls nur für Produkte.
• Berechnungsbasis brutto — legen Sie fest, ob der Prozentsatz auf die Brutto- oder die Nettosumme berechnet wird.

Beide Beträge sind kombinierbar. Die angewendete Formel lautet:

gebühr = feste_gebühr + (basis × prozentuale_gebühr / 100)

Grenzen und Gratis-Schwelle

• Mindestgebühr — ergibt die Berechnung einen niedrigeren Betrag, wird dieses Minimum angewendet. 0 = kein Minimum.
• Höchstgebühr — begrenzt den Gebührenbetrag nach oben. 0 = kein Maximum.
• Gratis-Schwelle — erreicht die Brutto-Warenkorbsumme diesen Betrag, wird keine Gebühr berechnet. 0 = deaktiviert.

Anwendungsbedingungen

Vier Bedingungsfamilien erlauben es, präzise zu steuern, wann die Regel greift. Eine leere Liste bedeutet „keine Einschränkung“ bei diesem Kriterium.

• Kundengruppen — die Regel greift nur, wenn der Kunde einer der ausgewählten Gruppen angehört. Typischer Fall: Gebühren für Privatkunden anwenden und Geschäftskunden ausnehmen.
• Länder — basierend auf dem Land der Rechnungsadresse des Warenkorbs.
• Währungen — die Regel greift nur bei den ausgewählten Währungen.
• Mindest- / Höchstwarenkorbsumme — die Regel greift nur, wenn die Brutto-Warenkorbsumme in diesem Bereich liegt. 0 deaktiviert die jeweilige Grenze.

Im Multistore-Betrieb ermöglicht ein zusätzliches Feld Shops die Zuordnung der Regel zu einem oder mehreren Shops. Bleibt es leer, gilt die Regel für alle Shops.

Auswertungsreihenfolge der Regeln

Für eine bestimmte Zahlungsart ruft das Modul alle aktiven Regeln ab, die dieses Modul (oder „Alle“) betreffen, sortiert nach aufsteigender Priorität und anschließend nach Kennung. Es wertet die Bedingungen jeder Regel in dieser Reihenfolge aus und wendet die erste Regel an, deren Bedingungen sämtlich erfüllt sind. Die nachfolgenden Regeln werden ignoriert.

Sonderfall der Gratis-Schwelle: Passt eine Regel, erreicht der Warenkorb aber ihre Gratis-Schwelle, wird keine Gebühr angewendet — und das Modul wertet die nachfolgenden Regeln nicht aus. Der Wegfall ist somit eine endgültige Entscheidung und kein bloßes „Weiter zur nächsten Regel“.

MwSt.-Verwaltung

Zwei Einstellungen bestimmen die steuerliche Behandlung der Gebühren:

• Beträge brutto eingegeben — geben Sie an, ob die von Ihnen eingetragenen Beträge (feste Gebühr, Grenzen) die MwSt. bereits enthalten.
• Steuerregel — die auf die Gebühr angewendete PrestaShop-Steuerregel. Wählen Sie Keine Steuer für Gebühren ohne MwSt.

Das Modul ermittelt den anwendbaren Satz aus der Steuerregel und der Rechnungsadresse des Kunden und leitet daraus die Aufschlüsselung ab:

• Bei Eingabe brutto: netto = brutto / (1 + Satz).
• Bei Eingabe netto: brutto = netto × (1 + Satz).

Beide Werte werden zusammen mit dem angewendeten Satz für Ihre Buchhaltung auf der Bestellung gespeichert.

Berechnungsbeispiel

Regel: feste Gebühr 1,00 € + 2 % des Warenkorbs, Brutto-Basis Produkte + Versand, Höchstgrenze 5,00 €, Beträge brutto eingegeben, MwSt. 19 %.

• Warenkorb: 120,00 € brutto Produkte + 5,00 € brutto Versand = Basis 125,00 €.
• Bruttogebühr: 1,00 + (125,00 × 2 / 100) = 3,50 € brutto.
• Unter der Grenze von 5,00 €: unverändert übernommen.
• Aufschlüsselung: netto = 3,50 / 1,19 = 2,94 €, MwSt. = 0,56 €.

Anzeige auf Kundenseite

Ist die Option Gebühren im Checkout anzeigen aktiviert, berechnet das Modul die Gebühr für jede verfügbare Zahlungsart und übergibt sie an das Frontoffice. Auf der Seite /order:

• Der Gebührenbetrag wird neben dem Label jeder betroffenen Zahlungsart ergänzt.
• Unter der Liste der Zahlungsarten erscheint ein Hinweis für die aktuell gewählte Option, der sich in Echtzeit aktualisiert, wenn der Kunde die Zahlungsart wechselt.

Diese Anzeige ist rein informativ: Der tatsächlich berechnete Betrag wird bei der Bestellvalidierung serverseitig neu ermittelt.

Anwendung auf die Bestellung

Bei der Bestellvalidierung (Hook actionValidateOrder) berechnet das Modul die Gebühr für die tatsächlich verwendete Zahlungsart neu und:

1. aktualisiert die Bestellsummen (total_paid, total_paid_tax_incl, total_paid_tax_excl sowie gegebenenfalls total_paid_real);
2. aktualisiert die Rechnungssummen, falls bereits eine Rechnung existiert;
3. aktualisiert den erfassten Zahlungsbetrag, damit er mit dem eingezogenen Betrag übereinstimmt;
4. speichert die Gebührenzeile (Label, netto, brutto, Satz) in der Tabelle df_payment_fee_order.

Die Gebührenzeile wird anschließend auf der Bestellbestätigungsseite, in der Bestellübersicht des Kunden, auf der Bestellseite im Backoffice sowie in der Bestätigungs-E-Mail angezeigt.

Ein Schutzmechanismus verhindert die doppelte Verarbeitung: Besitzt eine Bestellung bereits eine Gebührenzeile, unternimmt das Modul nichts.

Kompatibilität mit Zahlungs-Gateways

• Offline-Zahlungen (Überweisung, Scheck, Nachnahme, Zahlung im Ladengeschäft): Die Funktionsweise ist vollständig und ohne Einschränkung. Der Kunde sieht die Gebühr, Bestellung und Rechnung enthalten sie, und Sie ziehen den angezeigten Gesamtbetrag ein.
• Weiterleitungs- oder eingebettete Gateways (PayPal, Stripe, Banklösungen): Der an das Gateway übermittelte Betrag ist der vom Zahlungsmodul aus dem Warenkorb berechnete Betrag. Je nach Gateway und Konfiguration enthält dieser Betrag die Gebühr möglicherweise nicht. Prüfen Sie das Verhalten vor dem Livegang in einer Testumgebung.

Für Letztere sind zwei Ansätze üblich: Gebührenregeln auf Offline-Zahlungsarten beschränken oder den Betrag auf Gateway-Seite erfassen bzw. anpassen. Unser Support berät Sie je nach eingesetztem Gateway.

Multistore und Mehrsprachigkeit

Multistore — jede Regel wird über das Feld Shops im Formular einem oder mehreren Shops zugeordnet. Ausgewertet werden nur Regeln, die dem aktuellen Shop zugeordnet sind. Eine ohne Auswahl gespeicherte Regel gilt für alle Shops.

Mehrsprachigkeit — das Label jeder Regel ist in alle aktiven Shopsprachen übersetzbar. Ist das Label in der Sprache des Kunden nicht gepflegt, greift das Modul auf das globale Label aus den Moduleinstellungen zurück.

Fehlerbehebung

Die Gebühren werden im Checkout nicht angezeigt

• Prüfen Sie, ob die Option Gebühren im Checkout anzeigen in den Moduleinstellungen aktiviert ist.
• Prüfen Sie, ob die Regel aktiv ist und die betreffende Zahlungsart (oder „Alle“) adressiert.
• Prüfen Sie, ob der Kontext des Kunden alle Bedingungen erfüllt: Gruppe, Rechnungsland, Währung, Warenkorbsumme.
• Stellen Sie sicher, dass der Warenkorb die Gratis-Schwelle der Regel nicht erreicht.
• Leeren Sie den PrestaShop-Cache und laden Sie den Browser hart neu (Strg+F5), um altes JavaScript zu verwerfen.

Die Gebühren werden angezeigt, aber nicht zur Bestellung hinzugefügt

Sowohl die Berechnung im Checkout als auch bei der Validierung verwendet den technischen Namen des Zahlungsmoduls. Erfasst Ihr Zahlungsmodul ein vom technischen Namen abweichendes Label, prüfen Sie in der Tabelle df_payment_fee_order, ob für die Bestellung eine Zeile angelegt wurde. Ist das nicht der Fall, legen Sie zur Überprüfung eine Regel für Alle Zahlungsarten an und wenden Sie sich anschließend mit dem Namen des verwendeten Zahlungsmoduls an den Support.

Eine Regel greift nie, obwohl sie korrekt aussieht

Vermutlich passt eine höher priorisierte Regel (niedrigerer Prioritätswert) zuerst. Denken Sie daran, dass nur die erste passende Regel angewendet wird. Erhöhen Sie den Prioritätswert generischer Regeln oder verfeinern Sie die Bedingungen konkurrierender Regeln.

Der MwSt.-Betrag erscheint falsch

Prüfen Sie die Übereinstimmung zwischen der Einstellung Beträge brutto eingegeben und den von Ihnen eingetragenen Werten. Ein brutto eingegebener Betrag bei einer auf netto gestellten Einstellung (oder umgekehrt) verschiebt die Aufschlüsselung. Prüfen Sie außerdem, ob die gewählte Steuerregel für das Rechnungsland des Kunden gilt.

Der Checkout ist langsam oder friert ein

Stellen Sie sicher, dass Sie Modulversion 1.0.0 oder höher verwenden, leeren Sie den PrestaShop-Cache und laden Sie den Browser hart neu (Strg+F5), um eine zwischengespeicherte JavaScript-Version zu entfernen.

Deinstallation

Deinstallieren Sie das Modul über den Modulmanager. Die Deinstallation entfernt den Admin-Tab, die Konfigurationsvariablen und sämtliche Modultabellen einschließlich der Historie der auf Bestellungen angewendeten Gebühren. Bereits auf bestehenden Bestellungen erfasste Summen bleiben unverändert.