Charitable Pro 1.8.13+ kann die tatsächliche Verarbeitungsgebühr, die von Ihrem Zahlungs-Gateway berechnet wird, für jede Spende erfassen. Wenn aktiviert, wird die Gebühr auf der Admin-Seite der einzelnen Spende angezeigt und in CSV-Spendenexporten enthalten.

Unterstützte Gateways: Stripe, PayPal (Standard / IPN)

---

Inhaltsverzeichnis

---

Voraussetzungen

• Charitable Pro: Version 1.8.13 oder höher
• Gateway: Stripe oder PayPal (Standard). Andere Gateways werden nicht unterstützt.

---

So funktioniert's

Die Gebührenverfolgung ist passiv – sie erfasst die vom Gateway gemeldete Gebühr zum Zeitpunkt der Zahlungsbestätigung, ohne zusätzliche API-Aufrufe.

Stripe: Die Verarbeitungsgebühr wird aus dem balance_transaction.fee -Feld des Stripe-Charge-Objekts gelesen, wenn der Stripe-Webhook die Zahlungsbestätigung verarbeitet. Die Gebühr wird von der kleinsten Währungseinheit des Gateways (Cents) in einen Dezimalbetrag umgerechnet, bevor sie gespeichert wird.

PayPal: Die Verarbeitungsgebühr wird aus dem mc_fee -Feld in der PayPal IPN-Benachrichtigungsnutzlast gelesen. Sie wird unverändert gespeichert, da PayPal sie bereits als Dezimalbetrag sendet.

In beiden Fällen wird die Gebühr einmal gespeichert und nie überschrieben. Wenn PayPal eine IPN erneut sendet oder Stripe ein doppeltes Webhook-Ereignis auslöst, wird der ursprüngliche Wert beibehalten (Idempotenz).

---

Gebührenverfolgung aktivieren

Die Gebührenverfolgung ist standardmäßig deaktiviert. Um sie zu aktivieren, fügen Sie den folgenden Codeausschnitt zu den functions.php Ihres Themes oder einem standortspezifischen Plugin hinzu:

add_filter( 'charitable_show_gateway_processing_fee', '__return_true' );

Keine weitere Konfiguration ist erforderlich. Sobald sie aktiviert ist, wird die Gebühr für alle neuen Stripe- und PayPal-Spenden ab sofort erfasst. Bestehende Spenden werden nicht rückwirkend aktualisiert.

---

Gebührenverfolgung deaktivieren

Entfernen Sie den obigen Codeausschnitt oder geben Sie explizit false zurück:

add_filter( 'charitable_show_gateway_processing_fee', '__return_false' );

Das Deaktivieren der Verfolgung stoppt die Erfassung neuer Gebühren. Bereits gespeicherte Gebührendaten für bestehende Spenden werden nicht gelöscht.

---

Wo die Gebühr angezeigt wird

Wenn die Gebührenverfolgung aktiviert ist, wird eine Zeile Gateway Processing Fee im Spenden-Meta-Bereich der Admin-Seite der einzelnen Spende angezeigt (Spenden – klicken Sie auf eine beliebige Spende, um sie anzuzeigen). Der Wert wird mit der Währung der Spende als Währungsbetrag formatiert.

Die Zeile wird automatisch für jedes andere Gateway als Stripe oder PayPal ausgeblendet, auch wenn der Filter aktiviert ist.

---

CSV-Export

Wenn die Gebührenverfolgung aktiviert ist, wird eine Spalte Gateway Processing Fee in die CSV-Exporte von Spenden aufgenommen. Der Wert wird als Währungsbetrag formatiert. Diese Spalte erscheint nicht in Exporten, wenn der Filter deaktiviert ist.

---

Nettobetrag

Eine Hilfsfunktion zur Berechnung des Nettobetrags nach Abzug der Gebühren ist verfügbar:

Net = Donation Total - Gateway Processing Fee - Stripe Connect Application Fee (if applicable)

Die Stripe Connect-Anwendungsgebühr (separat als _stripe_application_fee_amount gespeichert) ist nur auf Websites mit Stripe Connect vorhanden. Für Standard-Stripe- und PayPal-Spenden beträgt sie null.

Um den Nettobetrag im Code abzurufen:

$net = charitable_gateway_fees_get_net_amount( $donation );
// Returns a formatted currency string, or false if no fee data is stored.

---

Hinweise und Einschränkungen

• Gebührendaten werden nur ab dem Zeitpunkt der Aktivierung des Filters aufgezeichnet. Es gibt kein Werkzeug, um Gebühren für ältere Spenden rückwirkend zu erfassen.
• Die PayPal-Gebührenerfassung erfordert, dass IPN korrekt funktioniert. Wenn IPN nicht konfiguriert ist oder fehlschlägt, wird keine Gebühr erfasst.
• Die Stripe-Gebührenerfassung erfordert, dass der Stripe-Webhook aktiv ist und charge.succeeded - oder payment_intent.succeeded -Ereignisse mit balance_transaction erweitert liefert.
• Das Gebührenfeld wird nur in den Spenden-Admin-Metadaten und im CSV-Export für Stripe- und PayPal-Spenden angezeigt, selbst wenn für eine Spende von einem anderen Gateway irgendwie Gebührendaten vorhanden sind.
• Bei Stripe Connect-Konten wird die Plattform-Anwendungsgebühr (_stripe_application_fee_amount) separat gespeichert und zusätzlich zur Verarbeitungsgebühr abgezogen, wenn Nettobeträge berechnet werden.

---

Entwicklerreferenz

Filter

charitable_show_gateway_processing_fee – Steuert, ob die Erfassung von Gateway-Gebühren aktiv ist. Geben Sie true zur Aktivierung zurück, false zur Deaktivierung (Standard).

// Enable fee tracking site-wide.
add_filter( 'charitable_show_gateway_processing_fee', '__return_true' );

Meta-Schlüssel

Meta-Schlüssel	Beschreibung
_gateway_processing_fee	Der Betrag der Gateway-Verarbeitungsgebühr als Dezimalzahl (z. B. 0.59). Gespeichert im Spenden-Post.
_stripe_application_fee_amount	Stripe Connect Plattform-Anwendungsgebühr. Nur bei Stripe Connect-Spenden vorhanden.

Hooks

charitable_paypal_web_accept – Aktion, die ausgelöst wird, wenn eine PayPal IPN web_accept-Benachrichtigung empfangen wird. Das Gateway-Gebührenmodul hakt sich hier mit Priorität 10 ein, um mc_fee zu erfassen.

do_action( 'charitable_paypal_web_accept', $data, $donation_id );

charitable_default_donation_fields – Filter, der verwendet wird, um das Feld gateway_processing_fee im Charitable-Feldsystem zu registrieren. Wird nur registriert, wenn charitable_show_gateway_processing_fee true zurückgibt.

charitable_donation_admin_meta – Filter, der verwendet wird, um die Gebührenzeile aus den Spenden-Admin-Metadaten für nicht unterstützte Gateways auszublenden.

charitable_export_donations_format_money_fields – Filter, der verwendet wird, um gateway_processing_fee als geldformatierten Spalte in CSV-Exporten einzuschließen, wenn die Nachverfolgung aktiviert ist.