Update order status on dispute events

[jrodger]

Related to #526.

Changes proposed in this Pull Request

• Creates 3 new order statuses
• Updates order status on dispute events:
  • Dispute created - Order is moved to "Disputed" status
  • Dispute accepted - Order is moved to "Disputed - Accepted" status
  • Dispute lost - Order is moved to "Disputed - Lost" status
  • Dispute won - Order is moved back to it's pre-dispute status

Notes

• As discussed in p2-pc1FvE-1b, ideally we'd break some of this code out into a package so that we can apply the same order statuses in all our payment gateways (that handle disputes). The long term aim would be merging the behaviour into core.
• The link to the dispute details uses the URL that the WCPay server sent the webhook to. This should be fine in production, but for our dev environment ends up with a broken link because we can't access the internal address used by Docker containers. I don't think there is a better way to get the URL here?
• Wording of all the status changes and notes needs reviewing
• There's a lot of duplicate code related to extracting values from the incoming event. I've left this for now because it would be nice to land some refactoring of this webhook controller before we merge this PR. The changes in here definitely push it over the edge into "too big". Ditto for the lack of unit tests.

Dispute statuses on the order screen

Disputed order note

Accepted dispute order note

Lost dispute order note

Won dispute order note (and status moving back to pre-dispute status)

Testing instructions

• TODO

[marcinbot]

Other than some code cleanup, is there anything else blocking us from merging this? It seems like it would be really useful given that some people tend to miss the dispute notification emails.

As for the cleanup - we could create something like Order_Service responsible for managing the order metadata, statuses, etc. There are a few functions in the gateway class that could fit in it as well.

And the package idea is definitely worth exploring, but I don't think we should hold off this on that account.

[haszari]

@jrodger @marcinbot is this PR worth pursuing? We have a few issues that could benefit from a true "disputed" status.

• WC-pay disputes are disrupting WC-admin analytics #526
• Subscriptions: Automatically suspend subscription when dispute occurs #727
• Shoppers receive "order complete" emails when a dispute is closed #7928

[haszari]

Next steps here might be to:

• Review the PR and summarise the plan / changes intended in this PR, i.e. the delta from current code (other changes in this PR may have been implemented since).
• Review the relevant discussions in P2 and elsewhere.
• P2 summary to decide if this is worth pursuing as a project or maintenance fix.

[marcinbot]

is this PR worth pursuing?

The functionality is definitely worth pursuing. As for the PR - not sure. A lot has changed since 2 years ago, and given the size, fixing it might take more effort than writing this from scratch. We'd probably need to assign a new developer too. But yes, let's work towards shipping this.

[haszari]

But yes, let's work towards shipping this.

@marcinbot gut check - do you think we could ship an disputed order status fix as a maintenance issue, or do you think we'd need a project?

The functionality is definitely worth pursuing. As for the PR - not sure.

I'll add to Helix review queue as a first step.

Helix reviewer – this is an old stale PR, but might be good inspiration for fixing some other issues in the backlog. Feel free to timebox your review, and don't worry about testing, just review the code and highlight any ideas/content that we could reuse or adapt for better handling of order status in dispute flow. i.e. mine for gold 👷🏻⛏️

[marcinbot]

gut check - do you think we could ship an disputed order status fix as a maintenance issue, or do you think we'd need a project?

Probably not - we just need to think about it some more, but the actual work shouldn't be too difficult. I think James's original post outlines the 3 statuses pretty well. I wouldn't worry about the potential for reusability across gateways or merging to Core. That discussion is probably out of date. And every time it has been brought up we always ended up with unnecessarily complicated code and never actually merged anything 🤷

[haszari]

Summarising what's in this PR for posterity:

• Registers order statuses to match all stages of a dispute.
• Applies those statuses in webhook handling for disputes – i.e. implement the actual status values.
  • This includes stashing and restoring (from order meta) the previous dispute status, if the merchant wins dispute. E.g. if an order was completed, then disputed & won, it returns to completed; if (for some reason) the order was disputed when pending, flips back to pending. (I'm thinking of this as "stash & pop")

Note this PR implements webhook handling for disputes, which we have since implemented.

This seems good 🤔

Generally I don't see major technical blockers here. I'm curious why we didn't use these custom status values when we implemented dispute handling.

I'm curious if there's any risk or potential problem with core or third party code breaking the flow of our disputed status (e.g. overwriting it) – so there might be a blocker there.

However, I think it needs a wider discussion

As @jrodger noted:

• The wording & UX needs at least design review.
• There's a desire to share this behaviour & these status values more widely. E.g. across Woo-owned payment gateways, or even with core.

I think we should work to get these status values shipped as they would make the dispute flow work much more smoothly.

I think it's important to do this as core-first as we can, there are elements here that we should either align on or actually implement in core:

• The dispute status values - code name and user-facing wording.
• The rules / state machine for how we transition between status values.
  • Including to/from regular order status - e.g. the "stash and pop" mechanism.

Next steps

• Find any prior art & discussion (P2/internal/product/design) relating to disputed order status.
• Ideate what bugs and pain points this could fix/mitigate.
• P2 this as a proposal, with the status values and how order can transition between. (could be design-led)

Then we can decide whether to proceed, and where (WooPayments vs. WooCommerce core). If we proceed we will need to start afresh in a new PR as the relevant code has changed significantly.

FYI @souravdebnath1986 - we could consider adding explicit order statuses for disputes as a roadmap project.

[haszari]

Closing – this is too stale to proceed. See review for potential next steps – the idea is possibly worth pursuing!