Skip to content

[Backport to release/10.6] fix: place new gateways above offline PMs in payment settings#63648

Merged
oaratovskyi merged 2 commits intorelease/10.6from
cherry-pick-PR63604-to-release/10.6
Mar 12, 2026
Merged

[Backport to release/10.6] fix: place new gateways above offline PMs in payment settings#63648
oaratovskyi merged 2 commits intorelease/10.6from
cherry-pick-PR63604-to-release/10.6

Conversation

@woocommercebot
Copy link
Copy Markdown
Collaborator

@woocommercebot woocommercebot commented Mar 12, 2026

This PR is a cherry-pick of #63604 to release/10.6.

Original PR Description

Submission Review Guidelines:

Changes proposed in this Pull Request:

When a new payment gateway is installed (e.g., Stripe via the NOX flow), it was being placed at the absolute bottom of the payment providers list — below offline payment methods (BACS, Cheque, COD). This meant the newly installed gateway wouldn't be expanded by default on checkout and would be buried below less commonly used methods.

This PR fixes the placement logic so that newly installed gateways are inserted above the offline payment methods group, unless the merchant has customized the provider ordering (detected by checking whether the offline group is still in its default bottom position).

Closes WOOPLUG-6189.

How to test the changes in this Pull Request:

Using the WooCommerce Testing Instructions Guide, include your detailed testing instructions:

  1. Spin up a new JurassicNinja store with the WC on this PR's branch, WC Beta Tester (here's a direct create link)
  2. Go to the site's dashboard, click on WooCommerce, and skip the profiler by setting the store country to US.
  3. Navigate to WooCommerce > Settings > Payments
  4. Install and activate a new payment gateway plugin (e.g., Stripe) via the NOX onboarding flow.
    image
  5. Verify the newly installed gateway appears above the "Take offline payments" group, not at the very bottom of the list.
    image
  6. Now manually drag the offline payment methods group above another gateway (to simulate custom ordering).
  7. Install another new payment gateway plugin, e.g. Visa Acceptance Solutions.
  8. Verify the new gateway is placed at the bottom of the list (respecting the merchant's custom ordering).
  9. If you drag offline payment gateways to be the last item in the list, then new gateways will be placed above it again.

Milestone

Note: Check the box above to have the milestone automatically assigned when merged.
Alternatively (e.g. for point releases), manually assign the appropriate milestone.

Changelog entry

  • Automatically create a changelog entry from the details below.

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

Note: A changelog entry has already been manually created at plugins/woocommerce/changelog/fix-wooplug-6189-gateway-ordering.

Changelog Entry Details

Significance

  • Patch
  • Minor
  • Major

Type

  • Fix - Fixes an existing bug
  • Add - Adds functionality
  • Update - Update existing functionality
  • Dev - Development related task
  • Tweak - A minor adjustment to the codebase
  • Performance - Address performance issues
  • Enhancement - Improvement to existing functionality

Message

Place newly installed payment gateways above offline payment methods instead of at the bottom of the list.

Changelog Entry Comment

Comment

@oaratovskyi @claude @woocommercebot
fix: place new gateways above offline PMs in payment settings (#63604)
92b221f 
* fix: place new gateways above offline PMs instead of at end of list (WOOPLUG-6189)

When a new payment gateway is installed, place it above offline payment
methods instead of at the absolute end — unless the merchant has
customized the ordering. Adds is_offline_group_last() helper to detect
default vs custom ordering. Fixes both Payments.php gateway loop and
PaymentsProviders.php enhance_order_map() fallback.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* changelog: add entry for WOOPLUG-6189

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: correct test expectations for new gateway placement behavior

Update PaymentsProvidersTest and PaymentsTest to match the new behavior
where gateways are placed above offline PMs in default ordering.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: add assertNotEmpty for unused $data in PaymentsTest

Address CodeRabbit review nitpick: assert on $data return value
to silence static analysis warnings and add basic verification.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: align fallback placement logic between display and persistence paths

Both Payments.php and PaymentsProviders.php now use
Utils::order_map_add_at_order() with max()+1 for the "append at end"
fallback, ensuring consistent collision handling and correct end-placement
when order values have gaps.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* test: strengthen assertions and clean up test data providers

- Add assertGreaterThan for stripe > gateway1 to properly verify
  end-placement in custom ordering test
- Remove unused $new_gateway_id parameter from test method and data provider
- Replace bare strings with WC_Gateway_BACS::ID, WC_Gateway_Cheque::ID,
  WC_Gateway_COD::ID class constants for consistency

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* test: assert on final provider output instead of intermediate order map

Switch both placement tests to verify $data (the sorted providers list
returned to the UI) instead of the captured_order_map intermediate.
This tests actual behavior rather than implementation details.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* fix: skip suggestions in is_offline_group_last and extract shared placement method

- Add is_suggestion_order_map_id() skip in is_offline_group_last() so
  persisted suggestion entries don't cause false negatives
- Extract order_map_add_gateway() on PaymentsProviders as the single
  source of truth for new gateway placement logic
- Both display (Payments.php) and persistence (enhance_order_map) paths
  now delegate to the same method
- Add test cases for suggestion after offline group and missing offline
  group scenarios

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: oaratovskyi <oleksandr.aratovskyi@automattic.com>
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
@github-actions github-actions bot added this to the 10.6.0 milestone Mar 12, 2026
@github-actions github-actions bot added the plugin: woocommerce Issues related to the WooCommerce Core plugin. label Mar 12, 2026
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 12, 2026

Testing Guidelines

Hi @oaratovskyi ,

Apart from reviewing the code changes, please make sure to review the testing instructions (Guide) and verify that relevant tests (E2E, Unit, Integration, etc.) have been added or updated as needed.

Reminder: PR reviewers are required to document testing performed. This includes:

  • 🖼️ Screenshots or screen recordings.
  • 📝 List of functionality tested / steps followed.
  • 🌐 Site details (environment attributes such as hosting type, plugins, theme, store size, store age, and relevant settings).
  • 🔍 Any analysis performed, such as assessing potential impacts on environment attributes and other plugins, conducting performance profiling, or using LLM/AI-based analysis.

⚠️ Within the testing details you provide, please ensure that no sensitive information (such as API keys, passwords, user data, etc.) is included in this public issue.

@woocommercebot woocommercebot mentioned this pull request Mar 12, 2026
Merged
17 tasks
@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Mar 12, 2026 •
edited
Loading

Test using WordPress Playground

The changes in this pull request can be previewed and tested using a WordPress Playground instance.
WordPress Playground is an experimental project that creates a full WordPress instance entirely within the browser.

Test this pull request with WordPress Playground.

Note that this URL is valid for 30 days from when this comment was last updated. You can update it by closing/reopening the PR or pushing a new commit.

oaratovskyi
oaratovskyi approved these changes Mar 12, 2026
View reviewed changes
Copy link
Copy Markdown
Contributor

@oaratovskyi oaratovskyi left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

:shipit:

@oaratovskyi oaratovskyi merged commit f797107 into release/10.6 Mar 12, 2026
36 checks passed
@oaratovskyi oaratovskyi deleted the cherry-pick-PR63604-to-release/10.6 branch March 12, 2026 10:44
@github-actions github-actions bot added metric: feature freeze exception A tracking label for PRs that were merged after the feature freeze. needs: documentation The issue/PR requires documentation to be added. labels Mar 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@oaratovskyi oaratovskyi oaratovskyi approved these changes

Assignees

@oaratovskyi oaratovskyi

Labels

metric: feature freeze exception A tracking label for PRs that were merged after the feature freeze. needs: documentation The issue/PR requires documentation to be added. plugin: woocommerce Issues related to the WooCommerce Core plugin.

Projects

None yet

Milestone

10.6.0

Development

Successfully merging this pull request may close these issues.

2 participants

@woocommercebot @oaratovskyi