Intent to Ship: Payment Request: Allow payment handlers to report back internal errors

[Stephen McGruer]

Note: Sending before Privacy, WP Security, and Adoption approvals, due to short timeline to M149. I do not expect significant feedback from those channels as this is a small change to an existing API that already has support from WebKit where relevant (for the Payment Request API part).

Contact emails

smcg...@google.com, xuehu...@google.com

Explainer

https://github.com/w3c/payment-request/issues/1040

Specification

https://w3c.github.io/payment-request/#payment-handler-indicates-an-internal-error-algorithm

Summary

Enables payment handlers that are accessed via the Payment Request API to return distinct errors for "user cancelled" vs "internal payment app error". This allows web developers to build better flows for users, e.g. by retrying or falling back to a different flow when an internal app error occurs, whilst properly stopping the flow if the user wants to cancel. The Web-based Payment Handler API can indicate this difference based on what error they use to reject the promised passed to PaymentRequestEvent.respondWith. If the promise is rejected with an OperationError, then "internal app error" (OperationError) is returned to the merchant via the PaymentRequest.show(), otherwise "user cancel" (AbortError) is returned. Native app payment handler infrastructure is similarly updated, but is out of scope for web APIs.

Blink component

Blink>Payments

Web Feature ID

payment-request

Motivation

Currently, when PaymentRequest.show() is rejected due to an error in the underlying payment handler app, the only possible outcome is AbortError. This makes it difficult for payment apps using Payment Request to build good user flows, as it is difficult to differentiate between "call failed because user cancelled out of the payment app" and "call failed because the app had an internal error".

Initial public proposal

No information provided

TAG review

N/A - very minor API tweak (was briefly discussed with TAG member at TPAC 2025, who showed no concern)

TAG review status

Not applicable

Goals for experimentation

None

Risks

Interoperability and Compatibility

No information provided

Gecko: N/A Firefox does not ship Payment Request or Payment Handler.

WebKit: Positive (https://github.com/w3c/payment-request/pull/1050) Positive for the Payment Request change, N/A for the Web-based Payment Handler change as WebKit does not implement any Payment Handler other than Apple Pay (PR was reviewed by marcos @ webkit, who is doing their implementation)

Web developers: Positive Requested by both current + prospective payment handler adopters

Other signals:

Ergonomics

No expected ergonomic risks.

Activation

No expected activation risks - minor change adding a new error outcome for PaymentRequest.show()

Security

No known security risks.

WebView application risks

Does this intent deprecate or change behavior of existing APIs, such that it has potentially high risk for Android WebView-based applications?

This adds a new potential (error) return value for the PaymentRequest.show() API within WebView. This is considered low risk, both because a new error type shouldn't be a significant risk but also because PaymentRequest in webview is **disabled by default** and must be manually enabled by the webview embedder.

Debuggability

Standard devtools debugging; breakpoints + introspection of error types.

Will this feature be supported on all six Blink platforms (Windows, Mac, Linux, ChromeOS, Android, and Android WebView)?

Yes

Is this feature fully tested by web-platform-tests?

No
Manual WPTs added where possible - https://github.com/web-platform-tests/wpt/pull/59002, but Payment Request/Web-based Payment Handler do not have the necessary chromedriver automation currently to write fully fledged automated tests. Chrome source automated tests added as well, of course.

Flag name on about://flags

No information provided

Finch feature name

PaymentRequestSupportReportingAppError

Rollout plan

Will ship enabled for all users

Requires code in //chrome?

Technically, a tiny bit (UX code for web-based payment handlers, some browsertests are also in //chrome)

Tracking bug

https://crbug.com/473478138

Availability expectation

Payment Request level changes will be available in both Chromium and Safari, but Safari only supports Apple Pay as a payment method. Chromium browsers will also support both the web-based Payment Handler and native app Payment Handler support for it.

Estimated milestones

Shipping on desktop	149
Shipping on Android	149
Shipping on WebView	149

Anticipated spec changes

No open issues, although the general question of whether a single new error type (vs something generic like supporting arbitrary developer errors to be passed through) was debated between us and Apple. Marcos is following up with the TAG on the general principle because it's also relevant to the DC API. This might cause future changes, but they would likely be mostly backward-compatible (since OperationError would remain a valid error type to throw).

Link to entry on the Chrome Platform Status

https://chromestatus.com/feature/5942637229113344?gate=4777865385213952

This intent message was generated by Chrome Platform Status.

[Mike Taylor]

Do we have any existing Payment Request or Payment Handler positions? If so, it's probably fine to just add a comment to them about this change, but if not, we should request one.

WebKit: Positive (https://github.com/w3c/payment-request/pull/1050) Positive for the Payment Request change, N/A for the Web-based Payment Handler change as WebKit does not implement any Payment Handler other than Apple Pay (PR was reviewed by marcos @ webkit, who is doing their implementation)

Can we file an official request? 

--
You received this message because you are subscribed to the Google Groups "blink-dev" group.
To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CADY3Macn-SYc8C%2BMBr06%3Df2%3Ds%3D8oGHHrhGoG9q1wV2oMP3ZuWg%40mail.gmail.com.

[Alex Russell]

LGTM1

On Wednesday, April 29, 2026 at 6:29:54 AM UTC-7 Mike Taylor wrote:

On 4/28/26 7:49 a.m., 'Stephen McGruer' via blink-dev wrote:

Note: Sending before Privacy, WP Security, and Adoption approvals, due to short timeline to M149. I do not expect significant feedback from those channels as this is a small change to an existing API that already has support from WebKit where relevant (for the Payment Request API part).

Contact emails

smcg...@google.com, xuehuichen...@google.com

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+unsubscribe@chromium.org.

[Rick Byers]

LGTM2

On Wed, Apr 29, 2026 at 11:27 AM Alex Russell <sligh...@chromium.org> wrote:

LGTM1

On Wednesday, April 29, 2026 at 6:29:54 AM UTC-7 Mike Taylor wrote:

On 4/28/26 7:49 a.m., 'Stephen McGruer' via blink-dev wrote:

Note: Sending before Privacy, WP Security, and Adoption approvals, due to short timeline to M149. I do not expect significant feedback from those channels as this is a small change to an existing API that already has support from WebKit where relevant (for the Payment Request API part).

Contact emails

smcg...@google.com, xuehu...@google.com

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CADY3Macn-SYc8C%2BMBr06%3Df2%3Ds%3D8oGHHrhGoG9q1wV2oMP3ZuWg%40mail.gmail.com.

--

You received this message because you are subscribed to the Google Groups "blink-dev" group.

To unsubscribe from this group and stop receiving emails from it, send an email to blink-dev+...@chromium.org.
To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/815efbae-8db0-4e86-a90a-2b30401c6253n%40chromium.org.

[Stephen McGruer]

> Do we have any existing Payment Request or Payment Handler positions? If so, it's probably fine to just add a comment to them about this change, but if not, we should request one.

Done, https://github.com/mozilla/standards-positions/issues/23#issuecomment-4345224553

> Can we file an official request? 

Done, https://github.com/WebKit/standards-positions/issues/655 . I'm not sure they'll thank us for the overhead, though...

--

smcgruer • he / him

[Chris Harrelson]

LGTM3

To view this discussion visit https://groups.google.com/a/chromium.org/d/msgid/blink-dev/CADY3MafXpO5Vgb-J4ZnkAKeSVEkoNnV%2B-naMBGO4G%3D8Ficku3A%40mail.gmail.com.

[Mike Taylor]

On 4/29/26 11:40 a.m., Stephen McGruer wrote:

> Do we have any existing Payment Request or Payment Handler positions? If so, it's probably fine to just add a comment to them about this change, but if not, we should request one.

Done, https://github.com/mozilla/standards-positions/issues/23#issuecomment-4345224553

> Can we file an official request? 

Done, https://github.com/WebKit/standards-positions/issues/655 . I'm not sure they'll thank us for the overhead, though...

Thanks - if they would like to tell us that Marcos (or another WebKit member) merging a PR counts as an official standards position, I think we're happy to update our requirements. I can leave a comment in the issue suggesting as much.