Payment Handler Internal Error Reporting

at a glance

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

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

see also

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