Payment Handler Internal Error Reporting

at a glance

Status disagreement, both sides reported rather than resolved (fetched 2026-10-07): this page records the feature as "Shipped in Chrome 149 / Edge 149" with status "Enabled by default", while the ChromeStatus record 5942637229113344 reports a summary status of Proposed with is_released false (accurate as of 2026-05-25), though its ship stage still carries desktop, Android, and WebView milestone 149. Neither side is adjudicated here.

why it exists

The Payment Handler API lets a web-based payment app respond to PaymentRequest.show() by handling the paymentrequest event in a service worker and calling PaymentRequestEvent.respondWith(promise). Before Chrome 149, any rejection of that promise — whether caused by the user pressing "cancel" or by a crash inside the payment app — reached the merchant as an AbortError. There was no way to tell the two apart.

This matters because the correct merchant response differs: a user cancellation should keep the checkout flow open so the user can choose a different payment method, while an internal payment app error might warrant an error message, a fallback, or a retry. The new behaviour gives payment handlers a dedicated signal for internal failures.

shape of the change

Error type contract

Affected APIs

Behavior disagreement, both sides reported rather than resolved (fetched 2026-10-07): this page documents that PaymentRequest.show() rejects with OperationError for an internal payment app error and with AbortError for user cancellation, while the MDN PaymentRequest.show() reference lists AbortError, InvalidStateError, NotSupportedError, and SecurityError as its exception types, with no OperationError case. Neither side is adjudicated here.

example

Payment handler (service-worker.js) — signal internal error

self.addEventListener("paymentrequest", (event) => {
  event.respondWith(
    new Promise(async (resolve, reject) => {
      try {
        const result = await openPaymentWindow(event);
        if (result.userCancelled) {
          // User tapped "cancel" — AbortError signals cancellation.
          reject(new DOMException("User cancelled", "AbortError"));
          return;
        }
        resolve({
          methodName: event.methodData[0].supportedMethods,
          details: result.paymentDetails,
        });
      } catch (err) {
        // Internal failure (network error, crypto failure, etc.)
        // OperationError signals an internal payment app error — new in Chrome 149.
        reject(new DOMException("Payment app error: " + err.message, "OperationError"));
      }
    })
  );
});

Merchant page — handle both error types

const request = new PaymentRequest(methodData, details);

try {
  const response = await request.show();
  await processPayment(response);
  await response.complete("success");
} catch (err) {
  if (err.name === "AbortError") {
    // User explicitly cancelled — return to checkout.
    showCheckoutForm();
  } else if (err.name === "OperationError") {
    // Payment app had an internal failure — offer fallback or retry.
    showPaymentError("The payment app encountered an error. Please try again.");
    logToMonitoring("payment_app_internal_error", err.message);
  } else {
    throw err;
  }
}

browser support

Browser-support disagreement, both sides reported rather than resolved (fetched 2026-10-07): this page lists Firefox and Safari as No signal, while the ChromeStatus record 5942637229113344 reports the Firefox view as N/A with the note "Firefox does not ship Payment Request or Payment Handler" and the Safari view as Positive. Neither side is adjudicated here.

see also

• MDN: PaymentRequestEvent.respondWith()
• MDN: PaymentRequest.show()
• MDN: Web-based Payment Handler API
• W3C Payment Request specification