Upgrading from 2.x

What migrates

Everything a gateway’s settings page used to hold, per gateway:

• the fixed and percentage amounts, the minimum and maximum
• what the percentage is based on (shipping, coupons, taxes, other fees)
• taxable or not, tax class, whether the amount includes tax
• the fee title and its placeholders
• the two “don’t charge when shipping is free” rules

Every method whose 2.x fee fields were touched at all is switched on in the new screen during the migration — including one that carried a title, caps, tax handling or a disable rule but charged nothing, so putting an amount back is one field rather than a rebuild. Methods left at 2.x’s own defaults are listed but off. The migration runs once, on the first load after the update, and again only if a version change calls for it. It is idempotent: running it twice changes nothing.

An admin notice tells you it happened and names the methods it carried over.

Where the fields went

Fees used to be fields at the bottom of each gateway’s own settings page. They are now all on one screen — WooCommerce → Settings → Pay for Payment — with the gateways listed on the left. Gateways whose settings pages had no room for extra fields (WooPayments, Stripe, Klarna, other React-based gateways) can carry a fee for the first time.

What behaves differently

Three things, each deliberate, each a fix for something 2.x got wrong.

Everything else is reproduced to the penny: the fee maths, the percentage base options, the caps, the placeholders, the VAT-exempt rule, the multi-currency conversions and the WPML string names. The release was audited line by line against 2.2.2 before it shipped.

What to check

Ten minutes on a staging copy is worth more than this page:

1. Note the fee on a real basket before updating, for each method you charge on.
2. Update. Open the new screen and confirm each of those methods shows as on, with the numbers you expect.
3. Load the same basket and read the fee again. Identical is the expected result. If it is not, the second section above is the first suspect — a mixed-tax-class basket with “inherit” is the case where a change is correct rather than a bug.
4. If the store used the woocommerce_pay4pay_get_current_gateway_settings filter, read the snippet note below.

Going back

3.0 writes its settings under new option names and never touches the 2.x values inside each gateway’s settings. Installing 2.2.2 again from the Advanced view on wordpress.org brings every fee back as it was. Uninstalling 3.0 removes what 3.0 created and deliberately leaves the 2.x configuration alone, for the same reason.

The only thing lost on a rollback is anything you set up in 3.0 that 2.x has no equivalent for — a second fee tier on a method, for example.

Custom code

Every woocommerce_pay4pay_* filter kept its name and signature. A snippet written for 2.x runs unchanged; it now receives one extra trailing argument, the index of the fee rule being calculated, which it is free to ignore.

Two notes if you use the whole-configuration filter, woocommerce_pay4pay_get_current_gateway_settings: it shapes a fee for a method that is switched on in the settings screen (a method whose fee lived entirely in your code was switched on for you during the upgrade), and COD’s “enable for shipping methods” restriction is read from the gateway itself rather than from the array you return. The filter reference has the detail.