Payment Handler API

Limited availability

This feature is not Baseline because it does not work in some of the most widely-used browsers.

secure contexts (HTTPS), in some or all supporting browsers.

Experimental: This is an experimental technology
Check the Browser compatibility table carefully before using this in production.

Note: This feature is available in Web Workers.

The Payment Handler API provides a standardized set of functionality for web applications to directly handle payments, rather than having to be redirected to a separate site for payment handling.

When a merchant website initiates payment via the Payment Request API, the Payment Handler API handles discovery of applicable payment apps, presenting them as choices to the user, opening a payment handler window once a choice has been made to allow the user to enter their payment details, and handling the payment transaction with the payment app.

Communication with payment apps (authorization, passing of payment credentials) is handled via Service Workers.

Concepts and usage

On a merchant website, a payment request is initiated by the construction of a new PaymentRequest object:

const request = new PaymentRequest(
  [
    {
      supportedMethods: "https://bobbucks.dev/pay",
    },
  ],
  {
    total: {
      label: "total",
      amount: { value: "10", currency: "USD" },
    },
  },
);

The supportedMethods property specifies a URL representing the payment method supported by the merchant. To use more than one payment method, you would specify them in an array of objects, like this:

const request = new PaymentRequest(
  [
    {
      supportedMethods: "https://alicebucks.dev/pay",
    },
    {
      supportedMethods: "https://bobbucks.dev/pay",
    },
  ],
  {
    total: {
      label: "total",
      amount: { value: "10", currency: "USD" },
    },
  },
);

{ "name": "Pay with BobBucks", "short_name": "BobBucks", "description": "This is an example of the Payment Handler API.", "icons": [ { "src": "images/manifest/icon-192x192.png", "sizes": "192x192", "type": "image/png" }, { "src": "images/manifest/icon-512x512.png", "sizes": "512x512", "type": "image/png" } ], "serviceworker": { "src": "service-worker.js", "scope": "/", "use_cache": false }, "start_url": "/", "display": "standalone", "theme_color": "#3f51b5", "background_color": "#3f51b5", "related_applications": [ { "platform": "play", "id": "com.example.android.samplepay", "min_version": "1", "fingerprints": [ { "type": "sha256_cert", "value": "4C:FC:14:C6:97:DE:66:4E:66:97:50:C0:24:CE:5F:27:00:92:EE:F3:7F:18:B3:DA:77:66:84:CD:9D:E9:D2:CB" } ] } ] }

self.addEventListener("canmakepayment", (e) => { e.respondWith( new Promise((resolve, reject) => { someAppSpecificLogic() .then((result) => { resolve(result); }) .catch((error) => { reject(error); }); }), ); });

let payment_request_event; let resolver; let client; / `self` is the global object in service worker self.addEventListener("paymentrequest", async (e) => { if (payment_request_event) { / If there's an ongoing payment transaction, reject it. resolver.reject(); } / Preserve the event for future use payment_request_event = e; / ... });

navigator.serviceWorker.register("serviceworker.js").then((registration) => { registration.paymentManager.userHint = "Card number should be 16 digits"; registration.paymentManager .enableDelegations(["shippingAddress", "payerName"]) .then(() => { / ... }); / ... });

Interfaces

CanMakePaymentEvent: The event object for the canmakepayment event, fired on a payment app's service worker when it has been successfully registered to signal that it is ready to handle payments.
PaymentManager: Used to manage various aspects of payment app functionality. Accessed via the ServiceWorkerRegistration.paymentManager property.
PaymentRequestEvent Experimental: The event object for the PaymentRequest.show() method.

Extensions to other interfaces

canmakepayment event: Fired on a payment app's ServiceWorkerGlobalScope when it has been successfully registered, to signal that it is ready to handle payments.
paymentrequest event: Fired on a payment app's PaymentRequest.show() method.
ServiceWorkerRegistration.paymentManager: Returns a payment app's PaymentManager instance, which is used to manage various payment app functionality.

Specification
Payment Handler API # the-paymentrequestevent

Specification

Payment Handler API
# the-paymentrequestevent

Payment Handler API

Concepts and usage

Making payment apps available

Checking whether the payment app is ready to pay with

Handling the payment

Managing payment app functionality

Interfaces

Extensions to other interfaces

Specifications

Browser compatibility

See also