Charitable Pro 1.8.13+ can record the actual processing fee charged by your payment gateway against each donation. When enabled, the fee appears on the individual donation admin page and is included in CSV donation exports.
Supported gateways: Stripe, PayPal (Standard / IPN)
Table des matières
Exigences
- Charitable Pro: Version 1.8.13 or higher
- Gateway: Stripe or PayPal (Standard). Other gateways are not supported.
Comment ça marche
Fee tracking is passive – it captures the fee reported by the gateway at the moment payment is confirmed, with no extra API calls.
Stripe: The processing fee is read from the balance_transaction.fee field on the Stripe charge object when the Stripe webhook processes the payment confirmation. The fee is converted from the gateway’s smallest currency unit (cents) to a decimal amount before being stored.
PayPal: The processing fee is read from the mc_fee field in the PayPal IPN notification payload. It is stored as-is since PayPal already sends it as a decimal amount.
In both cases the fee is stored once and never overwritten. If PayPal retries an IPN or Stripe fires a duplicate webhook event, the original value is preserved (idempotency).
Enabling Fee Tracking
Fee tracking is disabled by default. To enable it, add the following snippet to your theme’s functions.php or a site-specific plugin:
add_filter( 'charitable_show_gateway_processing_fee', '__return_true' );No other configuration is needed. Once enabled, the fee will be recorded for all new Stripe and PayPal donations going forward. Existing donations are not retroactively updated.
Disabling Fee Tracking
Remove the snippet above, or explicitly return false:
add_filter( 'charitable_show_gateway_processing_fee', '__return_false' );Disabling tracking stops new fees from being recorded. It does not delete fee data already stored against existing donations.
Where the Fee Appears
When fee tracking is enabled, a Gateway Processing Fee row appears in the donation meta section of the individual donation admin page (Donations – click any donation to view it). The value is formatted as a currency amount using the donation’s currency.
The row is hidden automatically for any gateway other than Stripe or PayPal, even if the filter is enabled.
CSV Export
When fee tracking is enabled, a Gateway Processing Fee column is included in donation CSV exports. The value is formatted as a currency amount. This column does not appear in exports when the filter is disabled.
Net Amount
A helper function is available to calculate the net amount received after fees:
Net = Donation Total - Gateway Processing Fee - Stripe Connect Application Fee (if applicable)The Stripe Connect application fee (stored separately as _stripe_application_fee_amount) is only present on sites using Stripe Connect. For standard Stripe and PayPal donations it is zero.
To retrieve the net amount in code:
$net = charitable_gateway_fees_get_net_amount( $donation );
// Returns a formatted currency string, or false if no fee data is stored.Notes and Limitations
- Fee data is only recorded going forward from when the filter is enabled. There is no tool to backfill fees for older donations.
- PayPal fee capture requires IPN to be working correctly. If IPN is not configured or is failing, no fee will be recorded.
- Stripe fee capture requires the Stripe webhook to be active and delivering
charge.succeededorpayment_intent.succeededevents withbalance_transactionexpanded. - The fee field is only shown in the donation admin meta and CSV export for Stripe and PayPal donations, even if fee data somehow exists on a donation from another gateway.
- For Stripe Connect accounts, the platform application fee (
_stripe_application_fee_amount) is stored separately and is subtracted in addition to the processing fee when calculating net amounts.
Référence développeur
Filtre
charitable_show_gateway_processing_fee – Controls whether gateway fee tracking is active. Return true to enable, false to disable (default).
// Enable fee tracking site-wide.
add_filter( 'charitable_show_gateway_processing_fee', '__return_true' );Meta keys
| Meta key | Description |
|---|---|
_gateway_processing_fee | The gateway processing fee amount as a decimal float (for example, 0.59). Stored on the donation post. |
_stripe_application_fee_amount | Stripe Connect platform application fee. Only present on Stripe Connect donations. |
Hooks
charitable_paypal_web_accept – Action that fires when a PayPal IPN web_accept notification is received. The gateway fees module hooks into this at priority 10 to capture mc_fee.
do_action( 'charitable_paypal_web_accept', $data, $donation_id );charitable_default_donation_fields – Filter used to register the gateway_processing_fee field in the Charitable field system. Only registered when charitable_show_gateway_processing_fee returns true.
charitable_donation_admin_meta – Filter used to hide the fee row from the donation admin meta for unsupported gateways.
charitable_export_donations_format_money_fields – Filter used to include gateway_processing_fee as a money-formatted column in CSV exports when tracking is enabled.
