WPS Migration: Authorize payment #60044

Mayisha · 2025-07-28T06:25:21Z

Submission Review Guidelines:

I have followed the WooCommerce Contributing Guidelines and the WordPress Coding Standards.
I have checked to ensure there aren't other open Pull Requests for the same update/change.
I have reviewed my code for security best practices.
Following the above guidelines will result in quick merges and clear and detailed feedback when appropriate.

Changes proposed in this Pull Request:

Added authorization support for orders v2.
When Payment action is set to Authorize, we will send a request to the authorize_url instead of capture_url which is received in the CHECKOUT.ORDER.APPROVED webhook event.
This will create an authorized transaction in PayPal.
The order status is set as on-hold.
In legacy implementation, the payment is captured when the user changes the order status from on-hold to processing or completed. The same has been implemented for the new flow.
On order status change, we send a request to capture the authorized payment.
If the capture is successful, PayPal sends a PAYMENT.CAPTURE.COMPLETED webhook which is already covered in the code.

Closes PAYPAL-48

Screenshots or screen recordings:

How to test the changes in this Pull Request:

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

You will need a Business sandbox account (merchant) and a Personal sandbox account (shopper).
Set the deprecated PayPal gateway feature flag, and set the Orders v2 migration flag:

wp option patch update woocommerce_paypal_settings _should_load 'yes'
wp option patch update woocommerce_paypal_settings use_orders_v2 'yes'

Go to WooCommerce > Settings > Payments > and enable PayPal Standard.
Configure PayPal Standard's settings:

For PayPal email, enter your merchant sandbox account email.
Check Enable PayPal sandbox
Check Enable logging (optional, for logging)
For Payment action, select Authorize

To enable end-to-end testing, add the PayPal API client and secret (used by the feature branch's test proxy):

wp option update wc_paypal_api_client_id <YOUR-PAYPAL-CLIENT>
wp option update wc_paypal_api_client_secret <YOUR-PAYPAL-CLIENT-SECRET>

As a shopper, add a product to cart and go to checkout.
You should see PayPal as a payment option.
Click "Proceed to PayPal".
Use your Personal sandbox account credentials to log in and approve the purchase.
You should get redirected to the "Order Confirmation" page.
Wait a few seconds, and go to the wp-admin order page.
There should be an order note about payment authorization and the order status should be on-hold.
In the order details section, the transaction ID should be linked.
Click the transaction ID. It should take you to the PayPal transaction page. Confirm that the transaction status is Authorized.
Go back to the order edit page and change the order status to processing.
Wait a few seconds and refresh the page.
There should be an order note about payment capture.
Go to the PayPal transaction page. Confirm that the transaction status is Authorized.

Note

The behavior of capturing the authorized payment on order status change is in parity with the existing behavior.
From the PayPal dashboard, there is an option to capture the payment from the corresponding transaction page. This action is not working in my PP sandbox and it never gets captured. Theoretically, when the capture from the PP dashboard works it would send a PAYMENT.CAPTURE.COMPLETED webhook, which is already covered in the code.

Changelog entry

Automatically create a changelog entry from the details below.

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

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

Changelog Entry Comment

Comment

…ation

github-actions · 2025-07-28T06:25:35Z

Testing Guidelines

Hi @annemirasol ,

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.

Copilot

Pull Request Overview

This PR implements authorization support for PayPal Orders v2 API, allowing merchants to authorize payments instead of immediately capturing them. The key change enables a two-step payment flow where orders are initially authorized and later captured when the merchant changes the order status.

Adds new REST API endpoints for payment authorization and capturing authorized payments
Implements webhook handling for PAYMENT.AUTHORIZATION.CREATED events
Modifies the payment flow to support both authorize and capture actions based on payment intent

Reviewed Changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
class-wc-rest-paypal-webhooks-proxy-controller.php	Adds webhook forwarding for `PAYMENT.AUTHORIZATION.CREATED` events
class-wc-rest-paypal-proxy-controller.php	Implements new endpoints for authorizing payments and capturing authorized payments
class-wc-gateway-paypal-webhook-handler.php	Adds processing logic for authorization webhooks and updates payment flow to handle both authorize/capture actions
class-wc-gateway-paypal-request.php	Refactors payment processing to support both authorization and capture, adds method to capture previously authorized payments
class-wc-gateway-paypal.php	Updates the capture payment method to use Orders v2 API when enabled

...woocommerce/includes/rest-api/Controllers/Version3/class-wc-rest-paypal-proxy-controller.php

plugins/woocommerce/includes/gateways/paypal/includes/class-wc-gateway-paypal-request.php

...ns/woocommerce/includes/gateways/paypal/includes/class-wc-gateway-paypal-webhook-handler.php

github-actions · 2025-07-28T06:32:40Z

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.

annemirasol

Not necessarily blocking -- we can choose to tackle in a follow-up -- but for delayed capture I am getting the following log entry twice, when I manually capture the payment (by setting it to Processing). The payment gets captured successfully though.

[28-Jul-2025 21:32:35 UTC] (Proxy) PayPal capture authorized payment response: Array
(
    [name] => UNPROCESSABLE_ENTITY
    [message] => The requested action could not be performed, semantically incorrect, or failed business validation.
    [debug_id] => f678251ca5471
    [details] => Array
        (
            [0] => Array
                (
                    [issue] => AUTHORIZATION_ALREADY_CAPTURED
                    [description] => Authorization has already been captured.
                )

        )

    [links] => Array
        (
            [0] => Array
                (
                    [href] => https://developer.paypal.com/docs/api/payments/v2/#error-AUTHORIZATION_ALREADY_CAPTURED
                    [rel] => information_link
                    [encType] => application/json
                )

        )

)

...ns/woocommerce/includes/gateways/paypal/includes/class-wc-gateway-paypal-webhook-handler.php

…ation

annemirasol · 2025-07-28T21:58:07Z

From the PayPal dashboard, there is an option to capture the payment from the corresponding transaction page. This action is not working in my PP sandbox and it never gets captured. Theoretically, when the capture from the PP dashboard works it would send a PAYMENT.CAPTURE.COMPLETED webhook, which is already covered in the code.

It doesn't work for me either, and I don't see the "capture" event in my developer dashboard. I suggest we document and ask our integration engineer.

annemirasol · 2025-07-28T22:05:04Z

Fix lint errors from bad merge

Sorry, I introduced some bad formatting when I merged in the testmode PR.

github-actions · 2025-07-31T12:11:19Z

⚠️ API Documentation Reminder

Hi @Mayisha! Your PR contains REST API changes. Please consider updating the REST API documentation if your changes affect the public API.

Changed API files:

plugins/woocommerce/includes/rest-api/Controllers/Version3/class-wc-rest-paypal-proxy-controller.php
plugins/woocommerce/includes/rest-api/Controllers/Version3/class-wc-rest-paypal-webhooks-proxy-controller.php

Mayisha added 9 commits July 26, 2025 00:06

add proxy

e2a7ff5

send request to authorize payment

a7d2ea0

process authorization event

0d078ce

add proxy webhook

5407c58

add proxy endpoint for capturing authorized payment

2cd68eb

fix proxy code

4a9587a

save paypal status in order meta

6697ddb

capture the authorized payment on status change

e21a57c

Merge branch 'feature/paypal-wps-migration' into task/paypal-authoriz…

70968ef

…ation

Mayisha requested a review from Copilot July 28, 2025 06:25

github-actions bot added the plugin: woocommerce Issues related to the WooCommerce Core plugin. label Jul 28, 2025

Copilot AI reviewed Jul 28, 2025

View reviewed changes

Mayisha added 2 commits July 28, 2025 12:39

update notices and docs

6d24299

fix lint

b5d568d

Mayisha requested a review from annemirasol July 28, 2025 06:42

move translator comment to correct place

6cf968a

annemirasol changed the title ~~WPS Migration: Authoriza payment~~ WPS Migration: Authorize payment Jul 28, 2025

annemirasol approved these changes Jul 28, 2025

View reviewed changes

...ns/woocommerce/includes/gateways/paypal/includes/class-wc-gateway-paypal-webhook-handler.php Outdated Show resolved Hide resolved

Merge branch 'feature/paypal-wps-migration' into task/paypal-authoriz…

be11b09

…ation

Fix lint errors from bad merge

c8c7365

Mayisha added 5 commits July 31, 2025 16:07

get action string based on condition

2afea44

pass test mode to proxy

a6ec0ee

fix order note

ea277f7

consider test mode in proxy

c482e59

fix lint

f2fcb54

Mayisha merged commit 8a3da25 into feature/paypal-wps-migration Jul 31, 2025
37 checks passed

Mayisha deleted the task/paypal-authorization branch July 31, 2025 12:11

Mayisha mentioned this pull request Jul 31, 2025

WPS Migration: Fix capture failure #60136

Merged

12 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

WPS Migration: Authorize payment #60044

WPS Migration: Authorize payment #60044

Uh oh!

Mayisha commented Jul 28, 2025

Uh oh!

github-actions bot commented Jul 28, 2025 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jul 28, 2025 •

edited

Loading

Uh oh!

annemirasol left a comment

Uh oh!

Uh oh!

annemirasol commented Jul 28, 2025

Uh oh!

annemirasol commented Jul 28, 2025

Uh oh!

Uh oh!

github-actions bot commented Jul 31, 2025

Uh oh!

Uh oh!

WPS Migration: Authorize payment #60044

WPS Migration: Authorize payment #60044

Uh oh!

Conversation

Mayisha commented Jul 28, 2025

Submission Review Guidelines:

Changes proposed in this Pull Request:

Screenshots or screen recordings:

How to test the changes in this Pull Request:

Changelog entry

Significance

Type

Message

Comment

Uh oh!

github-actions bot commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Testing Guidelines

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

github-actions bot commented Jul 28, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Test using WordPress Playground

Uh oh!

annemirasol left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

annemirasol commented Jul 28, 2025

Uh oh!

annemirasol commented Jul 28, 2025

Uh oh!

Uh oh!

github-actions bot commented Jul 31, 2025

Uh oh!

Uh oh!

github-actions bot commented Jul 28, 2025 •

edited

Loading

github-actions bot commented Jul 28, 2025 •

edited

Loading