DocumentationDevelopersFilter reference

Filter reference

Every filter from version 2 kept its name and signature, so a snippet written years ago still runs. Each now receives one extra argument: the index of the fee rule being calculated. Pro adds a few hooks of its own, listed at the end.

Free and ProUpdated for 3.0.0

Deciding whether to charge at all

The fee is added on woocommerce_cart_calculate_fees at PHP_INT_MAX - 1, so anything another plugin adds to the cart is already there when these run.

// No fee on baskets above 10 000.
add_filter( 'woocommerce_pay4pay_apply', function ( $apply ) {
    return WC()->cart->get_subtotal() < 10000;
} );

Filter	What it does
`woocommerce_pay4pay_apply`	Whether a charge is applied at all.
`..._applyfor_{gateway_id}`	The same decision, for one specific payment gateway.

Changing the amount

Four filters shape the configured values before the maths runs; one shapes the result after.

Filter	What it does
`..._charges_fixed`	The flat amount, before calculation.
`..._charges_percentage`	The percentage, before calculation.
`..._charges_minimum`	The floor on the percentage part. May be negative for discounts.
`..._charges_maximum`	The ceiling. Also may be negative.
`..._{gateway_id}_amount`	The final calculated amount, after caps.

Rewriting a whole configuration

apply_filters( 'woocommerce_pay4pay_get_current_gateway_settings', array $settings, WC_Payment_Gateway $gateway )

It hands you a method’s entire fee configuration for this request: the same fourteen pay4pay_* keys 2.x used — amounts, caps, tax handling, title, disable rules — merged on top of the gateway’s own settings array. Return false, null or an empty array to charge nothing. Keys you leave out keep their stored values.

It runs for the checkout charge, the order-pay charge and the fee preview alike, so all three agree.

Two things to know when porting a 2.x snippet

It shapes a fee for a method that is switched on in the settings screen. A method whose fee lives entirely in your code is switched on for you during the upgrade, and the screen tells you if one is ever missed.
COD’s enable_for_methods is read from the gateway itself, not from the array you return.

Finding the fee on an order

Fees go in through WC_Cart::add_fee(), so they land as ordinary fee line items. Three order-item meta keys tell them apart from anyone else’s:

Meta key	What it holds
`_pay4payment_fee_gateway`	The payment method id, e.g. `cod`.
`_pay4payment_fee_source`	`checkout`, `order_pay`, `admin` or `converted` — where the line was written.
`_pay4payment_fee_taxable`	On product lines only (Pro, fee as a product line): whether the fee was taxable, since a product line has no fee-line tax flag of its own.
`_pay4payment_fee_synced_gateway`	Order-level, not on the item: the gateway the sync last wrote a line for.

REST

GET|POST /wp-json/pay4payment/v1/settings   // capability: manage_woocommerce

The settings screen’s picker sources and the order-pay preview are REST routes too; they are on the REST API page.

Other hooks

These are newer than 2.x and are not part of the frozen set above. Most carry the pay4payment_ prefix; one settings filter still uses the older pay4pay_ one.

Hook	What it does
`pay4payment_condition_matches`	Filter. Decide a condition row yourself — a custom condition type arrives here as a non-match and your callback may return `true`. Receives the verdict, the row and the match context. Pro.
`pay4payment_chosen_payment_method`	Filter. Override which gateway the fee is worked out for on the current request — for checkouts that carry the choice somewhere the plugin cannot see.
`pay4payment_order_fee_sync`	Filter — `( bool $sync, WC_Order $order, string $gateway_id, string $source )`. Return `false` to keep the plugin from touching a given order’s fee line. `$source` is `order_pay`, `admin` or `checkout` (the Store API draft order).
`pay4payment_method_settings_saved`	Action — `( string $method_id, array $data )`. Fires after one method’s settings are stored. This is the hook the WPML string registration itself uses.
`pay4pay_settings_{tab}`	Filter — `( array $settings )`. Rewrites a settings array as it is read from the database; `{tab}` is `general` or a gateway id. A non-array return is ignored.
`pay4payment_is_plugin_fee_item`	Filter. Whether an order line counts as this plugin’s fee — used for orders written before the meta keys existed, where the title pattern is the only evidence.
`pay4payment_fee_product_sku`	Filter. The SKU of the managed “Payment fee” product; default `pay4payment-fee`. Pro.
`pay4payment_watchdog_min_missing`	Filter. How many fee-less orders on a gateway it takes before the watchdog warns; default 1. Receives the gateway id. Pro.
`pay4payment_fee_watchdog`	Action Scheduler hook the daily watchdog run fires on. Pro.
`pay4payment_is_premium`	Filter. The free↔Pro verdict, for development stores and tests. Returning `true` in the free build unlocks nothing — the Pro code is not in that zip.
`pay4payment_upgrade_offer_until`, `_code`, `_discount`	Filters. The launch offer shown to stores upgrading from 2.x: its end date, coupon code and label.

Need a hook that isn't here? Open an issue — filters get added when there's a real case for them.

Suggest a feature