Why build a payment app for the web

Web Payments provides a browser-native interface for collecting payment information. The underlying APIs can invoke both web-based payment apps and Android payment apps, so the same infrastructure supports either route.

Web-based payment apps have a few structural advantages over traditional redirect-based or pop-up payment flows:

  • Transactions complete in a modal within the merchant's page context, keeping the shopper oriented and reducing friction.
  • Because the APIs integrate into existing websites, you can build on your current user base without shipping a separate application.
  • Unlike platform-specific payment apps, users don't need to install anything ahead of time.

Browser support and architecture

Web Payments is not a single technology but a set of related APIs, so support varies by browser. Check the current compatibility matrix before committing to a specific integration path.

Every web-based payment app is built with standard web technologies and must include a service worker. That service worker acts as the mediator for payment requests by:

  • Opening a modal window that displays the payment app's interface.
  • Bridging the communication between the payment app and the merchant.
  • Obtaining authorization from the customer and passing the payment credential back to the merchant.

The end-to-end flow—how the merchant, service worker, and payment handler interact—is covered in the transaction lifecycle documentation.

Discovery and integration

For a merchant to use your payment app, they invoke the Payment Request API and specify the payment method you support via its payment method identifier. If that identifier is unique to your app, you can publish your own payment method manifest so browsers can discover your handler automatically.

Capabilities inside the payment handler window

The payment handler window is a regular top-level browsing context in Chrome, so most web APIs behave as they would in any other document. Two constraints apply: the viewport cannot be resized and window.open() is disabled.

The available authentication and verification APIs are worth noting for building sign-in flows:

  • WebAuthn: Already supported in the payment handler window. The standards body is investigating a tighter coupling between WebAuthn and Web Payments, but the current implementation already supports biometric sign-in.
  • Credential Management API: Planned, but still in active development for this context. It would allow automatic sign-in using credentials stored in the browser's password manager.
  • WebOTP: Also planned and still under development. It would enable programmatic extraction of one-time passwords from SMS messages to verify phone numbers inside the payment flow.

For known issues and upcoming features in the handler window, consult the public Chromium bug tracker.

Implementation roadmap

Building a web-based payment app breaks down into three components you'll implement in sequence: