[Enhancement]: Support recording transaction fees with a standardized `_transaction_fee` meta key (`transaction_fee` in HPOS)

[melek]

Describe the solution you'd like

Credit card and other payment method per-transaction fees are important for accurately reporting on revenue for modern shops. It is important enough that gateways like PayPal Payments (with _ppcp_paypal_fees), Stripe (with _stripe_fee), and many others already add their own meta fields on orders to record transaction fees.

There would be obvious benefits to a standardized total transaction fee field:

• Revenue reporting / analytics could be more accurate
• Integrations with systems like Xero could include transaction fee data without having per-gateway logic

I imagine the fee format should mirror the transaction_id field's design, probably as transaction_fee (and _transaction_fee on non-HPOS orders).

Minimum needed functionality

• A new transaction_fee of type decimal(26,8) column would be included on the new HPOS table, and a corresponding metadata field (likely _transaction_fee) would be part of the core order schema.
• A function/method to add the fee on an order should be included, with some documentation. I leave it up to those familiar with existing methods whether adding an optional second argument to payment_complete() would be better, or having a new method. For reference, here is the announcement post for when transaction IDs were added. Obviously with HPOS, we'd want to use CRUD methods over directly editing post meta.

Nice-to-have functionality

• Being able to add/edit the fee in the Edit Order screen on manual orders would be great, perhaps under the Billing information or similar to how an order fee is added. The field could only appear if the gateway enables the field. (In general, I like there to be some way to edit any standard column value in the UI).
• The Edit Order screen could display the transaction fee information when present, similar to how PayPal orders appear, with hooks / filters so the gateway can easily customize the fee / net deposit info to be appropriate for the gateway:

Describe alternatives you've considered

Individual gateways already implement a meta field like this, but it is always up to the developer how to implement it and what to name it. Without a standard API, this isn't that useful for reports or extensibility.

This approach doesn't touch current gateway implementations unless they have their own _transaction_fee meta field that doesn't contain a fitting data type. Even in that case, we can handle that by ignoring the field if the value is an unexpected type (and warn folks ahead of time to check their plugins if they use that field, since it is a common-sense name).

Additional context

Ultimately, there may be room in the future for a one-to-many Order → Transactions data structure, as hinted in this blog comment. That would be great for lots of reasons outside the scope of this request. In general, keeping the data structures flexible / extendable is nice for a system that needs to accommodate so many kinds of business as Woo does.

Similarly, with how complex payments have become I could imagine scenarios where multiple transaction fees should be recorded separately even for the same transaction. Maybe eventually an API similar to regular order fees would be useful to store such information.

That said, I think considering a 'base case' of a simple total in the field is a fine starting point, however, since if transactions are more comprehensively updated in the future, that'll likely introduce an opportunity to also extend how transaction fees would be handled. Transaction fees are such a normal issue for shops to think about, I really think they need to have a place in WooCommerce's core implementation.

To loop in an existing issue, #26991 is an existing discussion of showing PayPal Standard transaction fees. Not sure the status of this request with PayPal Standard being hidden in new installations.

There is some discussion on that issue from a community member on how this would help them with budgeting and reporting with PayPal.

[github-actions[bot]]

Hi @melek,

Thank you for opening the issue! It requires further feedback from the WooCommerce Core team.

We are adding the needs developer feedback label to this issue so that the Core team could take a look.

Please note it may take a few days for them to get to this issue. Thank you for your patience.

[barryhughes]

Thank you, this seems like a sensible idea and we'll look into next steps :+1:

[piinthecloud]

Adding a comment from the Community Slack by @pmgarman about what an ideal transaction ledger system might look like

https://shopify.dev/docs/api/admin-rest/2023-07/resources/transaction#resource-object << my dream for WC transactions

[Luc45]

Just dropping a comment here to say that during my weekly support rotation, a client wanted to see how much she was paying for PayPal/Stripe transaction fees, and this information wasn't available in her reportings. I believe it's because they are not standardized. So just dropping a thumbs up for this feature. :+1:

[masteradhoc]

Thumbs up from my side as well, just had a usecase that would have been great to have this data.