Show unsupported payment methods at the end of the payment method list

[daledupreez]

Changes proposed in this Pull Request:

This PR ensures that we sort the payment method list based on whether the payment method can be enabled at present. The underlying implementation centralises the logic for availability so we're always using the same core logic for whether a payment method is available (or not). The new logic is implemented in getPaymentMethodUnavailableReason(), with the possible return types declared as part of a PAYMENT_METHOD_UNAVAILABLE_REASONS constant. At present, we check for two conditions:

• If we have an official BNPL plugin active for Affirm and Klarna, we flag that plugin as unavailable due to a plugin conflict
• If the payment method doesn't support the store currency (i.e. where we show the "Requires currency" pill)

We then sort the list by available payment methods, then payment methods with a conflict, and then payment methods unavailable due to the store currency not being supported.

At an implementation level, I have tackled the following:

• Extracted most of the logic in the existing usePaymentMethodCurrencies() hook into a new getPaymentMethodCurrencies() helper
• Implemented a general-purpose getPaymentMethodUnavailableReason() helper to identify why a payment is (or is not) available, as well as a lightweight usePaymentMethodUnavailableReason() wrapper hook
  • The non-hook function is needed because we need to be able to call the code in a loop
• Implemented a new usePaymentMethodsSortedByAvailability() hook defined locally in the payment method list code, which relies on getPaymentMethodUnavailableReason() to determine whether each payment method is available (or not), and then performs the sort based on the result.
  • This seems to work OK, as payment methods with unsupported currencies don't seem to be draggable in the UI already, and those payment methods would not be displayed in any shopper-facing context anyway.

Open questions and concerns

• I don't know much about whether we allow multiple currencies to be accepted via the plugin (or via WooCommerce), so there may also be issues in this area. This may be a non-issue due to our (non)support for multiple currencies in a single store anyway.
• I've pushed down the checks for whether UPE is enabled -- we might need to pull those earlier in the code.

Screenshots

These screenshots are for a store that is configured to accept USD.

Before

After

Testing instructions

• Run this branch
• Ensure you have connected to Stripe
• Navigate to the payment method list
• Confirm that all payment methods that are not available for your store currency or have the Klarna or Affirm plugin enabled are shown at the end of the list
• Verify that all unavailable payment methods still have the appropriate pills displayed in the UI
• Verify that re-ordering the available payment methods continues to work (i.e. by dragging and dropping)
• Verify that trying to drag and drop the unavailable payment methods is a no-op

---

• Covered with tests (or have a good reason not to test in description ☝️)
• [N/A] Tested on mobile (or does not apply)

Changelog entry

• This Pull Request does not require a changelog entry. (Comment required below)

Changelog Entry Comment

Comment

Post merge

• Added testing instructions to the Release Testing Instructions wiki page (or does not apply)
• Added the needs docs label (or does not apply)
• Included this PR in the Release Thread scope (or does not apply)

[Copilot]

Pull Request Overview

This PR implements sorting of payment methods to prioritize those that support the store currency, moving unsupported payment methods to the end of the list. The implementation extracts existing currency logic into a reusable helper function and adds a new hook to handle the sorting logic.

Key changes:

• Refactored usePaymentMethodCurrencies hook by extracting core logic into getPaymentMethodCurrencies helper function
• Implemented usePaymentMethodsSortedByStoreCurrencySupport hook to sort payment methods based on store currency support
• Updated payment methods list component to use the sorted payment method IDs instead of the original order

Reviewed Changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
client/utils/use-payment-method-currencies.js	Extracted payment method currency logic into reusable getPaymentMethodCurrencies helper function
client/settings/general-settings-section/payment-methods-list.js	Added sorting hook and updated component to display payment methods sorted by currency support

[daledupreez]

Question: Is this check sufficient? Are there more conditions we should be using (or attaching to the data) to push payment methods into the trailing section?

[diegocurbelo]

There is also the case of payment methods disabled because of a plugin conflict (Affirm/Klarna):

[daledupreez]

I am torn on this one, to be honest. If they disable the other payment gateway, the payment method will be available immediately, so it could "move" unexpectedly for that case. So that case feels subtly different to me, and feels like adding it could lead to even weirder UX. 😐

[diegocurbelo]

The code changes look good... and it tests very well.

We are just missing the case of BNPL payment methods that might be disabled for "plugin conflicts"

--

As a side note, we might also want to consider hiding unavailable payment methods by default and a "Show unavailable payment methods" (or show all, or similar) checkbox at the top to show them. The list is getting pretty long, and half of them are usually unavailable because of currency restrictions:

[daledupreez]

As a side note, we might also want to consider hiding unavailable payment methods by default and a "Show unavailable payment methods" (or show all, or similar) checkbox at the top to show them. The list is getting pretty long, and half of them are usually unavailable because of currency restrictions:

I think this is something we probably should do, but I think we might need some basic design for that UX from @orcungogus. Maybe that makes sense for a follow-up PR and/or effort?

[malithsen]

This looks good to me and tests well. I really like Diego's idea on the toggle, but it makes sense to introduce that in a separate PR.

[diegocurbelo]

Code looks good, and tests well 🚢

We then sort the list by available payment methods, then payment methods with a conflict, and then payment methods unavailable due to the store currency not being supported.

And payment methods in each category can be re-ordered only among them, as expected:

Adding the show/hide unavailable payment methods toggle in a follow-up PR makes sense to me 👍🏼