Charitable Pro 1.8.13+ peut enregistrer les frais de traitement réels facturés par votre passerelle de paiement pour chaque don. Lorsqu'il est activé, les frais apparaissent sur la page d'administration du don individuel et sont inclus dans les exportations de dons au format CSV.
Passerelles prises en charge : Stripe, PayPal (Standard / IPN)
Table des matières
Exigences
- Charitable Pro : Version 1.8.13 ou supérieure
- Passerelle : Stripe ou PayPal (Standard). Les autres passerelles ne sont pas prises en charge.
Comment ça marche
Le suivi des frais est passif – il capture les frais signalés par la passerelle au moment où le paiement est confirmé, sans appels API supplémentaires.
Stripe : Les frais de traitement sont lus à partir du champ balance_transaction.fee de l'objet de paiement Stripe lorsque le webhook Stripe traite la confirmation du paiement. Les frais sont convertis de la plus petite unité monétaire de la passerelle (cents) en un montant décimal avant d'être stockés.
PayPal : Les frais de traitement sont lus à partir du champ mc_fee dans la charge utile de la notification IPN de PayPal. Ils sont stockés tels quels car PayPal les envoie déjà sous forme de montant décimal.
Dans les deux cas, les frais sont stockés une fois et ne sont jamais écrasés. Si PayPal réessaie une IPN ou si Stripe déclenche un événement webhook en double, la valeur d'origine est préservée (idempotence).
Activation du suivi des frais
Le suivi des frais est désactivé par défaut. Pour l'activer, ajoutez l'extrait de code suivant au fichier functions.php de votre thème ou à un plugin spécifique au site :
add_filter( 'charitable_show_gateway_processing_fee', '__return_true' );Aucune autre configuration n'est nécessaire. Une fois activé, les frais seront enregistrés pour tous les nouveaux dons Stripe et PayPal à venir. Les dons existants ne sont pas mis à jour rétroactivement.
Désactivation du suivi des frais
Supprimez l'extrait de code ci-dessus, ou retournez explicitement false :
add_filter( 'charitable_show_gateway_processing_fee', '__return_false' );La désactivation du suivi arrête l'enregistrement des nouveaux frais. Elle ne supprime pas les données de frais déjà stockées pour les dons existants.
Où les frais apparaissent
Lorsque le suivi des frais est activé, une ligne Frais de traitement de la passerelle apparaît dans la section méta du don sur la page d'administration du don individuel (Dons – cliquez sur n'importe quel don pour le visualiser). La valeur est formatée en tant que montant monétaire en utilisant la devise du don.
La ligne est automatiquement masquée pour toute passerelle autre que Stripe ou PayPal, même si le filtre est activé.
Export CSV
Lorsque le suivi des frais est activé, une colonne Frais de traitement de la passerelle est incluse dans les exportations CSV de dons. La valeur est formatée en tant que montant monétaire. Cette colonne n'apparaît pas dans les exportations lorsque le filtre est désactivé.
Montant net
Une fonction d'aide est disponible pour calculer le montant net reçu après déduction des frais :
Net = Donation Total - Gateway Processing Fee - Stripe Connect Application Fee (if applicable)Les frais de l'application Stripe Connect (stockés séparément sous _stripe_application_fee_amount) ne sont présents que sur les sites utilisant Stripe Connect. Pour les dons Stripe et PayPal standard, ils sont nuls.
Pour récupérer le montant net dans le code :
$net = charitable_gateway_fees_get_net_amount( $donation );
// Returns a formatted currency string, or false if no fee data is stored.Notes et limitations
- Les données de frais ne sont enregistrées qu'à partir du moment où le filtre est activé. Il n'existe aucun outil pour remplir rétroactivement les frais des dons plus anciens.
- La capture des frais PayPal nécessite que l'IPN fonctionne correctement. Si l'IPN n'est pas configuré ou échoue, aucun frais ne sera enregistré.
- La capture des frais Stripe nécessite que le webhook Stripe soit actif et délivre les événements
charge.succeededoupayment_intent.succeededavecbalance_transactiondéveloppé. - Le champ des frais n'est affiché dans les métadonnées d'administration des dons et l'exportation CSV que pour les dons Stripe et PayPal, même si des données de frais existent d'une manière ou d'une autre sur un don d'une autre passerelle.
- Pour les comptes Stripe Connect, les frais d'application de la plateforme (
_stripe_application_fee_amount) sont stockés séparément et sont soustraits en plus des frais de traitement lors du calcul des montants nets.
Référence développeur
Filtre
charitable_show_gateway_processing_fee – Contrôle si le suivi des frais de passerelle est actif. Retourne true pour activer, false pour désactiver (par défaut).
// Enable fee tracking site-wide.
add_filter( 'charitable_show_gateway_processing_fee', '__return_true' );Clés Meta
| Clé de métadonnées | Description |
|---|---|
_frais_de_traitement_passerelle | Le montant des frais de traitement de la passerelle sous forme de nombre décimal (par exemple, 0.59). Stocké sur le don. |
_montant_des_frais_de_plateforme_stripe | Frais d'application de la plateforme Stripe Connect. Présent uniquement sur les dons Stripe Connect. |
Crochets
charitable_paypal_web_accept – Action qui se déclenche lorsqu'une notification IPN web_accept de PayPal est reçue. Le module des frais de passerelle s'y accroche à la priorité 10 pour capturer mc_fee.
do_action( 'charitable_paypal_web_accept', $data, $donation_id );charitable_default_donation_fields – Filtre utilisé pour enregistrer le champ gateway_processing_fee dans le système de champs de Charitable. Uniquement enregistré lorsque charitable_show_gateway_processing_fee retourne true.
charitable_donation_admin_meta – Filtre utilisé pour masquer la ligne des frais des métadonnées d'administration des dons pour les passerelles non prises en charge.
charitable_export_donations_format_money_fields – Filtre utilisé pour inclure gateway_processing_fee en tant que colonne formatée en argent dans les exportations CSV lorsque le suivi est activé.
