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.