Registering a web-based payment app

What makes a web-based payment app

Web-based payment apps are Progressive Web Apps (PWAs) that run on top of service workers. The service worker is the core component: it captures payment requests from a merchant, launches the payment app, and mediates communication between the two parties. Configuring a payment app means registering the payment methods it supports and pointing the browser to its service worker, which you can do declaratively through the web app manifest.

Browser support for Web Payments varies because the feature set is made up of several independent technologies. Check the current support matrix before committing to an implementation approach.

Declaring payment capabilities in the manifest

To configure a web-based payment app declaratively, serve a web app manifest with the following properties:

• name
• icons
• serviceworker
  • src
  • scope
  • use_cache

The manifest alone isn't enough — make sure your payment method manifest points to the web app manifest correctly, as described in the guide on setting up a payment method.

Just-in-time service worker registration

If your web app manifest is already configured and served properly, you get just-in-time (JIT) service worker registration for free. The browser takes care of the rest, so no additional coding is required on your end.

Debugging the payment flow

Developing a web-based payment app frontend means switching between the merchant context and the payment app context. These tips apply to Chrome.

Local development without HTTPS headaches

The Payment Request API and the Web-based Payment Handler API require a secure context (HTTPS) with a valid certificate. Localhost and internal company servers often don't qualify, but Chrome exempts http://localhost by default. For other hosts, you can launch Chrome with flags to bypass the certificate check:

• --ignore-certificate-errors
• --unsafely-treat-insecure-origin-as-secure=http://*.corp.company.com

macOS

/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --ignore-certificate-errors --unsafely-treat-insecure-origin-as-secure=http://*.corp.company.com

Windows

chrome.exe --ignore-certificate-errors --unsafely-treat-insecure-origin-as-secure=http://*.corp.company.com

See the Chromium documentation for more on running Chrome with runtime flags.

Testing on mobile

Use Chrome DevTools to port forward your local web server to an Android device and test from a mobile browser. You can also attach desktop DevTools to Android Chrome for full remote debugging of the page on the device.

Tracking service worker events

For local development, DevTools can display Web-based Payment Handler API events. On the merchant context, open DevTools and navigate to the Application pane, then the "Payment Handler" section. Enable "Show events from other domains" and hit the "Record" button to start capturing events sent to the service worker that handles payments.

Where to go next

The next step is understanding how the service worker orchestrates a payment transaction during runtime.