Payment Handler API

2. Overview of Handling Payment Requests

In this document we envision the following flow:

An origin requests permission from the user to handle payment requests for a set of supported payment methods. For example, a user visiting a retail or bank site may be prompted to register a payment handler from that origin. The origin establishes the scope of the permission but the origin's capabilities may evolve without requiring additional user consent.
Payment handlers are defined in service worker code.
The PaymentManager is used to set a list of payment instruments. Each payment instrument provides data to the user agent to improve the user experience of selecting payment credentials:
- The method and optional capabilities inform the user agent decision whether to display this instrument as a candidate for payment.
- When the instrument matches what the payee accepts, the user agent may display the name and icon. These provide hints about payment credentials that the user agent will return in the PaymentHandlerResponse if the user selects this instrument.
When the merchant (or other payee) calls the [payment-request] method canMakePayment() or show() (e.g., when the user pushes a button on a checkout page), the user agent computes a list of candidate payment handlers, comparing the payment methods accepted by the merchant with those supported by registered payment handlers. For payment methods that support additional filtering, either merchant and payment handler capabilities are compared or CanMakePaymentEvent is used as part of determining whether there is a match.
The user agent displays a set of choices to the user: the registered instruments of the candidate payment handlers. The user agent displays these choices using information (labels and icons) provided at registration or otherwise available from the Web app.
When the user (the payer) selects an instrument, the user agent fires a PaymentRequestEvent (cf. the user interaction task source) in the service worker whose PaymentManager the instrument was registered with. The PaymentRequestEvent includes some information from the PaymentRequest (defined in [payment-request]) as well as additional information (e.g., origin and selected instrument).
Once activated, the payment handler performs whatever steps are necessary to handle the payment request, and return an appropriate payment response to the payee. If interaction with the user is necessary, the payment handler can open a window for that purpose.
The user agent receives a response asynchronously once the payment handler has finished handling the request. The response becomes the PaymentResponse (of [payment-request]).

Note

An origin may implement a payment app with more than one service worker and therefore multiple payment handlers may be registered per origin. The handler that is invoked is determined by the selection made by the user of a payment instrument. The service worker which stored the payment instrument with its PaymentManager is the one that will be invoked.

2.1 Handling a Payment Request

This section is non-normative.

A payment handler is a Web application that can handle a request for payment on behalf of the user.

The logic of a payment handler is driven by the payment methods that it supports. Some payment methods, such as basic-card expect little to no processing by the payment handler which simply returns payment card details in the response. It is then the job of the payee website to process the payment using the returned data as input.

In contrast, some payment methods, such as a crypto-currency payments or bank originated credit transfers, require that the payment handler initiate processing of the payment. In such cases the payment handler will return a payment reference, endpoint URL or some other data that the payee website can use to determine the outcome of the payment (as opposed to processing the payment itself).

Handling a payment request may include numerous interactions: with the user through a new window or other APIs (such as [WebCryptoAPI]) or with other services and origins through web requests or other means.

This specification does not address these activities that occur between the payment handler accepting the PaymentRequestEvent and the payment handler returning a response. All of these activities which may be required to configure the payment handler and handle the payment request, are left to the implementation of the payment handler, including:

how the user establishes an account with an origin that provides payment services.
how an origin authenticates a user.
how communication takes place between the payee server and the payee Web application, or between a payment app origin and other parties.

Thus, an origin will rely on many other Web technologies defined elsewhere for lifecycle management, security, user authentication, user interaction, and so on.

2.2 Structure of a Web Payment App

This section is non-normative.

Architecture of a (Web) payment apps as defined in this specification. — Figure 1 A Web payment app is associated with an origin. Payment handlers respond to `PaymentRequestEvent`s. `PaymentManager`s manage the definition, display, and user selection of `PaymentInstrument`s. A `PaymentInstrument` supports one or more payment methods.

2.3 Relation to Other Types of Payment Apps

This section is non-normative.

This specification does not address how third-party mobile payment apps interact (through proprietary mechanisms) with user agents, or how user agents themselves provide simple payment app functionality.

Different types of payment apps. Payment Handler API is for Web apps. — Figure 2 Payment Handler API enables Web apps to handle payments. Other types of payment apps may use other (proprietary) mechanisms.

3. Registration

One registers a payment handler with the user agent when assigning the first PaymentInstrument to it through the set() method.

3.1 Extension to the `ServiceWorkerRegistration` interface

This specification extends the ServiceWorkerRegistration interface with the addition of a paymentManager attribute.

partial interface ServiceWorkerRegistration {
  [SameObject] readonly attribute PaymentManager paymentManager;
};

The paymentManager attribute exposes payment handler functionality in the service worker.

3.2 `PaymentManager` interface

[SecureContext, Exposed=(Window,Worker)]
interface PaymentManager {
  [SameObject] readonly attribute PaymentInstruments instruments;
  attribute DOMString userHint;
};

The PaymentManager is used by payment handlers to manage their associated instruments and supported payment methods.

3.2.1 `instruments` attribute

This attribute allows manipulation of payment instruments associated with a service worker (and therefore its payment handler). To be a candidate payment handler, a handler must have at least one registered payment instrument to present to the user. That instrument needs to match the payment methods and required capabilities specified by the payment request.

3.2.2 `userHint` attribute

When displaying payment handler name and icon, the user agent may use this string to improve the user experience. For example, a user hint of "**** 1234" can remind the user that a particular card is available through this payment handler. When a agent displays all payment instruments available through a payment handler, it may cause confusion to display the additional hint.

3.3 `PaymentInstruments` interface

[SecureContext, Exposed=(Window,Worker)]
interface PaymentInstruments {
    Promise<boolean>           delete(DOMString instrumentKey);
    Promise<any> get(DOMString instrumentKey);
    Promise<sequence<DOMString>>  keys();
    Promise<boolean>           has(DOMString instrumentKey);
    Promise<void>              set(DOMString instrumentKey, PaymentInstrument details);
    Promise<void>           clear();
};

The PaymentInstruments interface represents a collection of payment instruments, each uniquely identified by an instrumentKey. The instrumentKey identifier will be passed to the payment handler to indicate the PaymentInstrument selected by the user, if any.

3.3.1 `delete()` method

When called, this method executes the following steps:

Let p be a new promise.
Return p and perform the remaining steps in parallel:
If the collection contains a PaymentInstrument with a matching instrumentKey, remove it from the collection and resolve p with true.
Otherwise, resolve p with false.

3.3.2 `get()` method

When called, this method executes the following steps:

Let p be a new promise.
Return p and perform the remaining steps in parallel:
If the collection contains a PaymentInstrument with a matching instrumentKey, resolve p with that PaymentInstrument.
Otherwise, resolve p with undefined.

3.3.3 `keys()` method

When called, this method executes the following steps:

Let p be a new promise.
Return p and perform the remaining steps in parallel:
Resolve p with a Sequence that contains all the instrumentKeys for the PaymentInstruments contained in the collection, in original insertion order.

3.3.4 `has()` method

When called, this method executes the following steps:

Let p be a new promise.
Return p and perform the remaining steps in parallel:
If the collection contains a PaymentInstrument with a matching instrumentKey, resolve p with true.
Otherwise, resolve p with false.

3.3.5 `set()` method

When called, this method executes the following steps:

Let registration be the PaymentInstrument's associated service worker registration.
If registration has no active worker, then reject a Promise with an "InvalidStateError" DOMException and terminate these steps.
Upon user agent discretion and depending on user consent, optionally return a Promise rejected with a NotAllowedError.
If the icons member of details is present, then:
1. Let convertedIcons be the result of running the convert image objects algorithm passing details.icons as the argument.
2. If the convertedIcons is an empty Sequence, then return a Promise rejected with a TypeError.
3. Set details.icons to convertedIcons.
Let p be a new promise.
Return p and perform the remaining steps in parallel:
If the icons member of details is present, then for each icon in details.icons:
1. If the user agent wants to display the icon, then:
  1. Let fetchedImage be the result of steps to fetch an image resource passing icon as the argument.
  2. Set icon.[[fetchedImage]] to fetchedImage.
If the collection contains a PaymentInstrument with a matching instrumentKey, replace it with the PaymentInstrument in details.
Otherwise, insert the PaymentInstrument in details as a new member of the collection and associate it with the key instrumentKey.
Resolve p.

3.3.6 `clear()` method

When called, this method executes the following steps:

Let p be a new promise.
Return p and perform the remaining steps in parallel:
Remove all PaymentInstruments from the collection and resolve p.

3.3.7 `PaymentInstrument` dictionary

dictionary PaymentInstrument {
  required DOMString name;
  sequence<ImageObject> icons;
  DOMString method;
  object capabilities;
};

name member: The name member is a string that represents the label for this PaymentInstrument as it is usually displayed to the user.
icons member: The icons member is an array of image objects that can serve as iconic representations of the payment instrument when presented to the user for selection.
method member: The method member is the payment method identifier of the payment method supported by this instrument.
capabilities member: The capabilities member is a list of payment-method-specific capabilities that this payment handler is capable of supporting for this instrument. For example, for the basic-card payment method, this object will consist of an object with two fields: one for supportedNetworks, and another for supportedTypes.

3.3.8 `ImageObject` dictionary

dictionary ImageObject {
    required USVString src;
    DOMString sizes;
    DOMString type;
};

src member: The src member is used to specify the ImageObject's source. It is a URL from which the user agent can fetch the image’s data.
sizes member: The sizes member is used to specify the ImageObject's sizes. It follows the spec of sizes member in HTML link element, which is a string consisting of an unordered set of unique space-separated tokens which are ASCII case-insensitive that represents the dimensions of an image. Each keyword is either an ASCII case-insensitive match for the string "any", or a value that consists of two valid non-negative integers that do not have a leading U+0030 DIGIT ZERO (0) character and that are separated by a single U+0078 LATIN SMALL LETTER X or U+0058 LATIN CAPITAL LETTER X character. The keywords represent icon sizes in raw pixels (as opposed to CSS pixels). When multiple image objects are available, a user agent MAY use the value to decide which icon is most suitable for a display context (and ignore any that are inappropriate). The parsing steps for the sizes member MUST follow the parsing steps for HTML link element sizes attribute.
type member: The type member is used to specify the ImageObject's MIME type. It is a hint as to the media type of the image. The purpose of this member is to allow a user agent to ignore images of media types it does not support.

3.3.9 Convert image objects

When this algorithm with inputImages parameter is invoked, the user agent must run the following steps:

Let outputImages be an empty Sequence of ImageObject.
For each image in inputImages:
1. If image.type is not a valid MIME type string or the value of type is not a supported media format, then return an empty Sequence of ImageObject.
2. If image.sizes is not a valid value, then return an empty Sequence of ImageObject.
3. Let url be the result of parsing image.src with the context object's relevant settings object's API base URL.
4. If url is failure, then return an empty Sequence of ImageObject.
5. If url's scheme is not "https", then return an empty Sequence of ImageObject.
6. Set image.src to url.
7. Append image to outputImages
Return outputImages.

According to the step 2.3, it is also possible to use the relative url for image.src. The following examples illustrate how relative URL resolution works in different execution contexts.

Example 1: Resolving the relative URL of image.src in window context.

<-- In this example, code is located in https://www.example.com/bobpay/index.html -->
<script>

const instrumentKey = "c8126178-3bba-4d09-8f00-0771bcfd3b11";
navigator.serviceWorker.register("/register/sw.js");
const registration = await navigator.serviceWorker.ready;
await registration.paymentManager.paymentInstruments.set({
  instrumentKey,
  {
    name: "My Bob Pay Account: john@example.com",
    method: "https://bobpay.com",
    icons: [{
      src: "icon/lowres.webp",
      sizes: "48x48",
      type: "image/webp"
    }]
  });

const storedInstrument =
  await registration.paymentManager.paymentInstruments.get(instrumentKey);

// storedInstrument.icons[0].src == "https://www.example.com/bobpay/icon/lowres.webp";

</script>

Example 2: Resolving the relative URL of image.src in service worker context.

// In this example, code is located in https://www.example.com/register/sw.js

const instrumentKey = "c8126178-3bba-4d09-8f00-0771bcfd3b11";
await self.registration.paymentManager.paymentInstruments.set({
  instrumentKey,
  {
    name: "My Bob Pay Account: john@example.com",
    method: "https://bobpay.com",
    icons: [{
      src: "../bobpay/icon/lowres.webp",
      sizes: "48x48",
      type: "image/webp"
    }]
  });

const storedInstrument =
  await registration.paymentManager.paymentInstruments.get(instrumentKey);

// storedInstrument.icons[0].src == "https://www.example.com/bobpay/icon/lowres.webp";

3.3.10 Registration Example

This section is non-normative.

The following example shows how to register a payment handler:

Example 3: Payment Handler Registration

button.addEventListener("click", async() => {
  if (!window.PaymentManager) {
    return; // not supported, so bail out.
  }

  navigator.serviceWorker.register("/sw.js");
  const registration = await navigator.serviceWorker.ready;

  // Excellent, we got it! Let's now set up the user's cards.
  await addInstruments(registration);
}, { once: true });

function addInstruments(registration) {
  return Promise.all([
    registration.paymentManager.instruments.set(
      "dc2de27a-ca5e-4fbd-883e-b6ded6c69d4f",
      {
        name: "Visa ending ****4756",
        method: "basic-card",
        capabilities: {
          supportedNetworks: ["visa"],
          supportedTypes: ["credit"]
        }
      }),

    registration.paymentManager.instruments.set(
      "c8126178-3bba-4d09-8f00-0771bcfd3b11",
      {
        name: "My Bob Pay Account: john@example.com",
        method: "https://bobpay.com"
      }),

    registration.paymentManager.instruments.set(
      "new-card",
      {
        name: "Add new credit/debit card to ExampleApp",
        method: "basic-card",
        capabilities: {
          supportedNetworks:
            ["visa", "mastercard", "amex", "discover"],
          supportedTypes: ["credit", "debit", "prepaid"]
        }
      }),
    ]);
  };

4. Can make payment

If the payment handler supports CanMakePaymentEvent, the user agent may use it to help with filtering of the available payment handlers.

Implementations may impose a timeout for developers to respond to the CanMakePaymentEvent. If the timeout expires, then the implementation will behave as if respondWith() was called with false.

4.1 Extension to `ServiceWorkerGlobalScope`

This specification extends the ServiceWorkerGlobalScope interface.

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler oncanmakepayment;
};

4.1.1 `oncanmakepayment` attribute

The oncanmakepayment attribute is an event handler whose corresponding event handler event type is canmakepayment.

4.2 The `CanMakePaymentEvent`

The CanMakePaymentEvent is used to check whether the payment handler is able to respond to a payment request.

[Exposed=ServiceWorker]
interface CanMakePaymentEvent : ExtendableEvent {
  constructor(DOMString type, CanMakePaymentEventInit eventInitDict);
  readonly attribute USVString topOrigin;
  readonly attribute USVString paymentRequestOrigin;
  readonly attribute FrozenArray<PaymentMethodData> methodData;
  void respondWith(Promise<boolean> canMakePaymentResponse);
};

The topOrigin, paymentRequestOrigin, methodData, and modifiers members share their definitions with those defined for PaymentRequestEvent.

4.2.1 `respondWith()` method

This method is used by the payment handler to indicate whether it can respond to a payment request.

4.2.2 `CanMakePaymentEventInit` dictionary

dictionary CanMakePaymentEventInit : ExtendableEventInit {
  USVString topOrigin;
  USVString paymentRequestOrigin;
  sequence<PaymentMethodData> methodData;
};

The topOrigin, paymentRequestOrigin, and methodData members share their definitions with those defined for PaymentRequestEvent.

4.3 Handling a CanMakePaymentEvent

Upon receiving a PaymentRequest, the user agent MUST run the following steps:

If user agent settings prohibit usage of CanMakePaymentEvent (e.g., in private browsing mode), terminate these steps.
Let registration be a ServiceWorkerRegistration.
If registration is not found, terminate these steps.
Fire Functional Event "canmakepayment" using CanMakePaymentEvent on registration with the following properties:

topOrigin

the serialization of the origin of the top level payee web page.

paymentRequestOrigin

the serialization of the origin of the context where PaymentRequest was initialized.

methodData

The result of executing the MethodData Population Algorithm.

modifiers

The result of executing the Modifiers Population Algorithm.

4.4 Example of handling the `CanMakePaymentEvent`

This section is non-normative.

This example shows how to write a service worker that listens to the CanMakePaymentEvent. When a CanMakePaymentEvent is received, the service worker always returns true.

Example 4: Handling the CanMakePaymentEvent

self.addEventListener("canmakepayment", function(e) {
  e.respondWith(true);
});

4.5 Filtering of Payment Instruments

Given a PaymentMethodData and a PaymentInstrument that match on payment method identifier, this algorithm returns true if this instrument can be used for payment:

Let instrument be the given PaymentInstrument.
Let methodName be the payment method identifier string specified in the PaymentMethodData.
Let methodData be the payment method specific data of PaymentMethodData.
Let paymentHandlerOrigin be the origin of the ServiceWorkerRegistration scope URL of the payment handler with this instrument.
Let paymentMethodManifest be the ingested and parsed payment method manifest for the methodName.
If methodName is a standardized payment method identifier or is a URL-based payment method identifier with the "*" string supported origins in paymentMethodManifest, filter based on capabilities:
1. For each key in methodData:
  1. If the intersection of methodData[key] and instrument.capabilities[key] is empty, return false.
2. Otherwise, return true.
Otherwise, if the URL-based payment method identifier methodName has the same origin as paymentHandlerOrigin, fire the CanMakePaymentEvent in the payment handler and return the result.
Otherwise, if supported origins in paymentMethodManifest is an ordered set of origins that contains the paymentHandlerOrigin, fire the CanMakePaymentEvent in the payment handler and return the result.
Otherwise, return false.

4.5.1 How to specify capabilities

This section is non-normative.

Example of how a payment handler should provide the list of all its active cards to the browser.

Example 5: Specifying capabilities

await navigator.serviceWorker.register("/pw/app.js");
const registration = await navigator.serviceWorker.ready;
registration.paymentManager.userHint = "(Visa ****1111)";
await registration.paymentManager.instruments.set(
  "12345",
  {
    name: "Visa ****1111",
    icons: [{
      src: "/pay/visa.png",
      sizes: "32x32",
      type: "image/png",
    }],
    method: "basic-card",
    capabilities: {
      supportedNetworks: ["visa"],
      supportedTypes: ["credit"],
    },
  });

In this case, new PaymentRequest([{supportedMethods: "basic-card"}], shoppingCart).canMakePayment() should return true because there's an active card in the payment handler. Note that new PaymentRequest([{supportedMethods: "basic-card", data: {supportedTypes: ["debit"]}}], shoppingCart).canMakePayment() would return false because of mismatch in supportedTypes in this example.

5. Invocation

Once the user has selected an Instrument, the user agent fires a PaymentRequestEvent and uses the subsequent PaymentHandlerResponse to create a PaymentReponse for [payment-request].

Issue 117: Support for Abort() being delegated to Payment Handler

Payment Request API supports delegation of responsibility to manage an abort to a payment app. There is a proposal to add a paymentRequestAborted event to the Payment Handler interface. The event will have a respondWith method that takes a boolean parameter indicating if the paymentRequest has been successfully aborted.

5.1 Extension to `ServiceWorkerGlobalScope`

This specification extends the ServiceWorkerGlobalScope interface.

partial interface ServiceWorkerGlobalScope {
  attribute EventHandler onpaymentrequest;
};

5.1.1 `onpaymentrequest` attribute

The onpaymentrequest attribute is an event handler whose corresponding event handler event type is PaymentRequestEvent.

5.2 The `PaymentMethodChangeResponse`

The PaymentMethodChangeResponse contains the updated total (optionally with modifiers) and possible errors resulting from user selection of a payment method within a payment handler.

dictionary PaymentMethodChangeResponse {
  DOMString error;
  PaymentCurrencyAmount total;
  FrozenArray<PaymentDetailsModifier> modifiers;
  object paymentMethodErrors;
};

5.2.1 `error` member

A human readable string that explains why the payment method cannot be used.

5.2.2 `total` member

Updated total based on the changed payment method. The total can change, for example, because the billing address of the payment method selected by the user changes the Value Added Tax (VAT).

5.2.3 `modifiers` member

Updated modifiers based on the changed payment method. For example, if the overall total has increased by €1.00 based on the billing address, then the totals specified in each of the modifiers should also increase by €1.00.

5.2.4 `paymentMethodErrors` member

Validation errors for the payment method, if any.

5.3 The `PaymentRequestEvent`

The PaymentRequestEvent represents the data and methods available to a Payment Handler after selection by the user. The user agent communicates a subset of data available from the PaymentRequest to the Payment Handler.

[Exposed=ServiceWorker]
interface PaymentRequestEvent : ExtendableEvent {
  constructor(DOMString type, PaymentRequestEventInit eventInitDict);
  readonly attribute USVString topOrigin;
  readonly attribute USVString paymentRequestOrigin;
  readonly attribute DOMString paymentRequestId;
  readonly attribute FrozenArray<PaymentMethodData> methodData;
  readonly attribute object total;
  readonly attribute FrozenArray<PaymentDetailsModifier> modifiers;
  readonly attribute DOMString instrumentKey;
  readonly attribute boolean requestBillingAddress;
  Promise<WindowClient?> openWindow(USVString url);
  Promise<PaymentMethodChangeResponse?> changePaymentMethod(DOMString methodName, optional object? methodDetails = null);
  void respondWith(Promise<PaymentHandlerResponse> handlerResponsePromise);
};

5.3.1 `topOrigin` attribute

Returns a string that indicates the origin of the top level payee web page. This attribute is initialized by Handling a PaymentRequestEvent.

5.3.2 `paymentRequestOrigin` attribute

Returns a string that indicates the origin where a PaymentRequest was initialized. When a PaymentRequest is initialized in the topOrigin, the attributes have the same value, otherwise the attributes have different values. For example, when a PaymentRequest is initialized within an iframe from an origin other than topOrigin, the value of this attribute is the origin of the iframe. This attribute is initialized by Handling a PaymentRequestEvent.

5.3.3 `paymentRequestId` attribute

When getting, the paymentRequestId attribute returns the [[details]].id from the PaymentRequest that corresponds to this PaymentRequestEvent.

5.3.4 `methodData` attribute

This attribute contains PaymentMethodData dictionaries containing the payment method identifiers for the payment methods that the web site accepts and any associated payment method specific data. It is populated from the PaymentRequest using the MethodData Population Algorithm defined below.

5.3.5 `total` attribute

This attribute indicates the total amount being requested for payment. It is of type PaymentCurrencyAmount dictionary as defined in [payment-request], and initialized with a structured clone of the total field of the PaymentDetailsInit provided when the corresponding PaymentRequest object was instantiated.

5.3.6 `modifiers` attribute

This sequence of PaymentDetailsModifier dictionaries contains modifiers for particular payment method identifiers (e.g., if the payment amount or currency type varies based on a per-payment-method basis). It is populated from the PaymentRequest using the Modifiers Population Algorithm defined below.

5.3.7 `instrumentKey` attribute

This attribute indicates the PaymentInstrument selected by the user. It corresponds to the instrumentKey provided to the PaymentManager.instruments interface during registration. An empty string means that the user did not choose a specific PaymentInstrument.

5.3.8 `requestBillingAddress` attribute

The value of PaymentOptions.requestBillingAddress in the PaymentRequest.

5.3.9 `openWindow()` method

This method is used by the payment handler to show a window to the user. When called, it runs the open window algorithm.

5.3.10 `changePaymentMethod()` method

This method is used by the payment handler to get updated total given such payment method details as the billing address. When called, it runs the change payment method algorithm.

5.3.11 `respondWith()` method

This method is used by the payment handler to provide a PaymentHandlerResponse when the payment successfully completes. When called, it runs the Respond to PaymentRequest Algorithm with event and handlerResponsePromise as arguments.

Issue 123: Share user data with payment app?

Should payment apps receive user data stored in the user agent upon explicit consent from the user? The payment app could request permission either at installation or when the payment app is first invoked.

5.3.12 `PaymentRequestEventInit` dictionary

dictionary PaymentRequestEventInit : ExtendableEventInit {
  USVString topOrigin;
  USVString paymentRequestOrigin;
  DOMString paymentRequestId;
  sequence<PaymentMethodData> methodData;
  PaymentCurrencyAmount total;
  sequence<PaymentDetailsModifier> modifiers;
  DOMString instrumentKey;
};

The topOrigin, paymentRequestOrigin, paymentRequestId, methodData, total, modifiers, and instrumentKey members share their definitions with those defined for PaymentRequestEvent

5.3.13 MethodData Population Algorithm

To initialize the value of the methodData, the user agent MUST perform the following steps or their equivalent:

Set registeredMethods to an empty set.
For each PaymentInstrument instrument in the payment handler's PaymentManager.instruments, add the value of instrument.method to registeredMethods.
Create a new empty Sequence.
Set dataList to the newly created Sequence.
For each item in PaymentRequest@[[methodData]] in the corresponding payment request, perform the following steps:
1. Set inData to the item under consideration.
2. Set commonMethods to the set intersection of inData.supportedMethods and registeredMethods.
3. If commonMethods is empty, skip the remaining substeps and move on to the next item (if any).
4. Create a new PaymentMethodData object.
5. Set outData to the newly created PaymentMethodData.
6. Set outData.supportedMethods to a list containing the members of commonMethods.
7. Set outData.data to a structured clone of inData.data.
8. Append outData to dataList.
Set methodData to dataList.

5.3.14 Modifiers Population Algorithm

To initialize the value of the modifiers, the user agent MUST perform the following steps or their equivalent:

Set registeredMethods to an empty set.
For each PaymentInstrument instrument in the payment handler's PaymentManager.instruments, add the value of instrument.method to registeredMethods.
Create a new empty Sequence.
Set modifierList to the newly created Sequence.
For each item in PaymentRequest@[[paymentDetails]].modifiers in the corresponding payment request, perform the following steps:
1. Set inModifier to the item under consideration.
2. Set commonMethods to the set intersection of inModifier.supportedMethods and registeredMethods.
3. If commonMethods is empty, skip the remaining substeps and move on to the next item (if any).
4. Create a new PaymentDetailsModifier object.
5. Set outModifier to the newly created PaymentDetailsModifier.
6. Set outModifier.supportedMethods to a list containing the members of commonMethods.
7. Set outModifier.total to a structured clone of inModifier.total.
8. Append outModifier to modifierList.
Set modifiers to modifierList.

5.4 Internal Slots

Instances of PaymentRequestEvent are created with the internal slots in the following table:

Internal Slot	Default Value	Description (non-normative)
[[windowClient]]	null	The currently active WindowClient. This is set if a payment handler is currently showing a window to the user. Otherwise, it is null.
[[fetchedImage]]	undefined	This value is a result of steps to fetch an image resource or a fallback image provided by the user agent.
[[respondWithCalled]]	false	YAHO

5.5 Handling a PaymentRequestEvent

Upon receiving a PaymentRequest by way of PaymentRequest.show() and subsequent user selection of a payment instrument, the user agent MUST run the following steps:

Let registration be the ServiceWorkerRegistration corresponding to the PaymentInstrument selected by the user.
If registration is not found, reject the Promise that was created by PaymentRequest.show() with an "InvalidStateError" DOMException and terminate these steps.
Fire Functional Event "paymentrequest" using PaymentRequestEvent on registration with the following properties:

topOrigin

the serialization of the origin of the top level payee web page.

paymentRequestOrigin

the serialization of the origin of the context where PaymentRequest was initialized.

methodData

The result of executing the MethodData Population Algorithm.

modifiers

The result of executing the Modifiers Population Algorithm.

total

A structured clone of the total field on the PaymentDetailsInit from the corresponding PaymentRequest.

paymentRequestId

The [[details]].id from the PaymentRequest.

instrumentKey

The instrumentKey of the selected PaymentInstrument, or the empty string if none was selected.

Then run the following steps in parallel, with dispatchedEvent:
1. Wait for all of the promises in the extend lifetime promises of dispatchedEvent to resolve.
2. If the payment handler has not provided a PaymentHandlerResponse, reject the Promise that was created by PaymentRequest.show() with an "OperationError" DOMException.

6. Windows

An invoked payment handler may or may not need to display information about itself or request user input. Some examples of potential payment handler display include:

The payment handler opens a window for the user to provide an authorization code.
The payment handler opens a window that makes it easy for the user to confirm payment using default information for that site provided through previous user configuration.
When first selected to pay in a given session, the payment handler opens a window. For subsequent payments in the same session, the payment handler (through configuration) performs its duties without opening a window or requiring user interaction.

A payment handler that requires visual display and user interaction, may call openWindow() to display a page to the user.

Note

Since user agents know that this method is connected to the PaymentRequestEvent, they SHOULD render the window in a way that is consistent with the flow and not confusing to the user. The resulting window client is bound to the tab/window that initiated the PaymentRequest. A single payment handler SHOULD NOT be allowed to open more than one client window using this method.

6.1 Open Window Algorithm

Issue 115: The Open Window Algorithm

This algorithm resembles the Open Window Algorithm in the Service Workers specification.

Issue 115: Open Window Algorithm

Should we refer to the Service Workers specification instead of copying their steps?

Let event be this PaymentRequestEvent.
If event's isTrusted attribute is false, return a Promise rejected with a "InvalidStateError" DOMException.
Let request be the PaymentRequest that triggered this PaymentRequestEvent.
Let url be the result of parsing the url argument.
If the url parsing throws an exception, return a Promise rejected with that exception.
If url is about:blank, return a Promise rejected with a TypeError.
If url's origin is not the same as the service worker's origin associated with the payment handler, return a Promise resolved with null.
If this algorithm is not triggered by user activation, return a Promise rejected with a "NotAllowedError" DOMException.
Let promise be a new Promise.
Return promise and perform the remaining steps in parallel:
If event.[[windowClient]] is not null, then:
1. If event.[[windowClient]].visibilityState is not "unloaded", reject promise with an "InvalidStateError" DOMException and abort these steps.
Let newContext be a new top-level browsing context.
Navigate newContext to url, with exceptions enabled and replacement enabled.
If the navigation throws an exception, reject promise with that exception and abort these steps.
If the origin of newContext is not the same as the service worker client origin associated with the payment handler, then:
1. Resolve promise with null.
2. Abort these steps.
Let client be the result of running the create window client algorithm with newContext as the argument.
Set event.[[windowClient]] to client.
Resolve promise with client.

6.2 Example of handling the `PaymentRequestEvent`

This section is non-normative.

This example shows how to write a service worker that listens to the PaymentRequestEvent. When a PaymentRequestEvent is received, the service worker opens a window to interact with the user.

Example 6: Handling the PaymentRequestEvent

self.addEventListener("paymentrequest", function(e) {
  e.respondWith(new Promise(function(resolve, reject) {
    self.addEventListener("message", listener = function(e) {
      self.removeEventListener("message", listener);
      if (e.data.hasOwnProperty("name")) {
        reject(e.data);
      } else {
        resolve(e.data);
      }
    });

    e.openWindow("https://www.example.com/bobpay/pay")
    .then(function(windowClient) {
      windowClient.postMessage(e.data);
    })
    .catch(function(err) {
      reject(err);
    });
  }));
});

Issue 128: Revisit examples

The Web Payments Working Group plans to revisit these two examples.

Using the simple scheme described above, a trivial HTML page that is loaded into the payment handler window to implement the basic card scheme might look like the following:

Example 7: Simple Payment Handler Window

<form id="form">
<table>
  <tr><th>Cardholder Name:</th><td><input name="cardholderName"></td></tr>
  <tr><th>Card Number:</th><td><input name="cardNumber"></td></tr>
  <tr><th>Expiration Month:</th><td><input name="expiryMonth"></td></tr>
  <tr><th>Expiration Year:</th><td><input name="expiryYear"></td></tr>
  <tr><th>Security Code:</th><td><input name="cardSecurityCode"></td></tr>
  <tr><th></th><td><input type="submit" value="Pay"></td></tr>
</table>
</form>

<script>
window.addEventListener("message", function(e) {
  var form = document.getElementById("form");
  /* Note: message sent from payment app is available in e.data */
  form.onsubmit = function() {
    /* See https://w3c.github.io/webpayments-methods-card/#basiccardresponse */
    var basicCardResponse = {};
    [ "cardholderName", "cardNumber","expiryMonth","expiryYear","cardSecurityCode"]
    .forEach(function(field) {
      basicCardResponse[field] = form.elements[field].value;
    });

    /* See https://w3c.github.io/payment-handler/#paymenthandlerresponse-dictionary */
    var paymentAppResponse = {
      methodName: "basic-card",
      details: details
    };

    e.source.postMessage(paymentAppResponse);
    window.close();
  }
});
</script>

7. Response

7.1 `PaymentHandlerResponse` dictionary

The PaymentHandlerResponse is conveyed using the following dictionary:

dictionary PaymentHandlerResponse {
DOMString methodName;
object details;
};

7.1.1 `methodName` attribute

The payment method identifier for the payment method that the user selected to fulfil the transaction.

7.1.2 `details` attribute

A JSON-serializable object that provides a payment method specific message used by the merchant to process the transaction and determine successful fund transfer.

The user agent receives a successful response from the payment handler through resolution of the Promise provided to the respondWith() function of the corresponding PaymentRequestEvent interface. The application is expected to resolve the Promise with a PaymentHandlerResponse instance containing the payment response. In case of user cancellation or error, the application may signal failure by rejecting the Promise.

If the Promise is rejected, the user agent MUST run the payment app failure algorithm. The exact details of this algorithm are left to implementers. Acceptable behaviors include, but are not limited to:

Letting the user try again, with the same payment handler or with a different one.
Rejecting the Promise that was created by PaymentRequest.show().

7.2 Change Payment Method Algorithm

When this algorithm is invoked with methodName and methodDetails parameters, the user agent MUST run the following steps:

Run the payment method changed algorithm with PaymentMethodChangeEvent event constructed using the given methodName and methodDetails parameters.
If event.updateWith(detailsPromise) is not run, return null.
If event.updateWith(detailsPromise) throws, rethrow the error.
If event.updateWith(detailsPromise) times out (optional), throw "InvalidStateError" DOMException.
Construct and return a PaymentMethodChangeResponse from the detailsPromise in event.updateWith(detailsPromise).

7.3 Respond to PaymentRequest Algorithm

When this algorithm is invoked with event and handlerResponsePromise parameters, the user agent MUST run the following steps:

If event's isTrusted is false, then throw an "InvalidStateError" DOMException and abort these steps.
If event's dispatch flag is unset, then throw an "InvalidStateError" DOMException and abort these steps.
If event.[[respondWithCalled]] is true, throw an "InvalidStateError" DOMException and abort these steps.
Set event.[[respondWithCalled]] to true.
Set the event's stop propagation flag and event's stop immediate propagation flag.
Add handlerResponsePromise to the event's extend lifetime promises
Increment the event's pending promises count by one.
Upon rejection of handlerResponsePromise:
1. Run the payment app failure algorithm and terminate these steps.
Upon fulfillment of handlerResponsePromise:
1. Let handlerResponse be the result of converting value to a PaymentHandlerResponse dictionary. If this throws an exception, run the payment app failure algorithm and terminate these steps.
2. If handlerResponse.methodName is not present or not set to one of the values from event.methodData, run the payment app failure algorithm and terminate these steps.
3. If handlerResponse.details is not present or not JSON-serializable, run the payment app failure algorithm and terminate these steps.
4. Let serializeMethodName be the result of StructuredSerialize with handlerResponse.methodName. Rethrow any exceptions.
5. Let serializeDetails be the result of StructuredSerialize with handlerResponse.details. Rethrow any exceptions.
6. The user agent MUST run the user accepts the payment request algorithm as defined in [payment-request], replacing steps 7 and 8 with these steps or their equivalent.
  1. Let methodName be the result of StructuredDeserialize with serializeMethodName. Rethrow any exceptions.
  2. Let details be the result of StructuredDeserialize with serializeDetails. Rethrow any exceptions.
  3. If any exception occurs in any of the above steps, then run the payment app failure algorithm and terminate these steps.
  4. Assign methodName to associated PaymentRequest's response.methodName.
  5. Assign details to associated PaymentReqeust's response.details.
Upon fulfillment or rejection of handlerResponsePromise, queue a microtask to perform the following steps:
1. Decrement the event's pending promises count by one.
2. Let registration be the context object's relevant global object's associated service worker's containing service worker registration.
3. If registration’s uninstalling flag is set, invoke Try Clear Registration with registration.
4. If registration is not null, invoke Try Activate with registration.

The following example shows how to respond to a payment request:

Example 8: Sending a Payment Response

paymentRequestEvent.respondWith(new Promise(function(accept,reject) {
  /* ... processing may occur here ... */
  accept({
    methodName: "basic-card",
    details: {
      cardHolderName:   "John Smith",
      cardNumber:       "1232343451234",
      expiryMonth:      "12",
      expiryYear :      "2020",
      cardSecurityCode: "123"
     }
  });
}));

Note

[payment-request] defines an ID that parties in the ecosystem (including payment app providers and payees) can use for reconciliation after network or other failures.

8. Security and Privacy Considerations

8.1 Information about the User Environment

The API does not share information about the user's registered payment handlers. Information from origins is only shared with the payee with the consent of the user.
User agents should not share payment request information with any payment handler until the user has selected that payment handler.
In a browser that supports Payment Handler API, when a merchant creates a PaymentRequest object with URL-based payment method identifiers, CanMakePaymentEvent will fire in registered payment handlers from a finite number of origins: the origins of the payment method manifests and their supported origins. This means that a registered payment handler will know that a user has visited a website before the user has selected that payment handler to complete a transaction. This behavior is similar to the status quo where a merchant embeds a third-party iframe in a checkout page. However, because user agents enable users to disable the CanMakePaymentEvent and users can choose to uninstall payment handlers, this approach improves upon the iframe status quo.
User agents should allow users to disable support for the CanMakePaymentEvent.

8.4 Secure Communications

See Service Worker security considerations
Payment method security is outside the scope of this specification and is addressed by payment handlers that support those payment methods.

8.5 Authorized Payment Apps

The party responsible for a payment method authorizes payment apps through a payment method manifest. See the Handling a CanMakePaymentEvent algorithm for details.
The user agent is not required to make available payment handlers that pose security issues. Security issues might include:
- Certificates that are expired, revoked, self-signed, and so on.
- Mixed content
- Page available through HTTPs redirects to one that is not.
- Payment handler is known from safe browsing database to be malicious
When a payment handler is unavailable for security reasons, the user agent should provide rationale to the payment handler developers (e.g., through console messages) and may also inform the user to help avoid confusion.

8.6 Supported Origin

Payment method manifests authorize origins to distribute payment apps for a given payment method. When the user agent is determining whether a payment handler matches the origin listed in a payment method manifest, the user agent uses the scope URL of the payment handler's service worker registration.

8.7 Data Validation

To mitigate the scenario where a hijacked payee site submits fraudlent or malformed payment method data (or, for that matter, payment request data) to the payee's server, the payee's server should validate the data format and correlate the data with authoritative information on the server such as accepted payment methods, total, display items, and shipping address.

8.8 Private Browsing Mode

When the Payment Request API is invoked in a "private browsing mode," the user agent should launch payment handlers in a private context. This will generally prevent sites from accessing any previously-stored information. In turn, this is likely to require either that the user log in to the origin or re-enter payment instrument details.
The CanMakePaymentEvent event should not be fired in private browsing mode. The user agent should behave as if respondWith() was called with false. We acknowledge a consequent risk: if an entity controls both the origin of the Payment Request API call and the origin of the payment handler, that entity may be able to deduce that the user may be in private browsing mode.

Payment Handler API

W3C Working Draft 21 October 2019

Abstract

Status of This Document

1. Introduction

2. Overview of Handling Payment Requests

2.1 Handling a Payment Request

2.2 Structure of a Web Payment App

2.3 Relation to Other Types of Payment Apps

3. Registration

3.1 Extension to the ServiceWorkerRegistration interface

3.2 PaymentManager interface

3.2.1 instruments attribute

3.2.2 userHint attribute

3.3 PaymentInstruments interface

3.3.1 delete() method

3.3.2 get() method

3.3.3 keys() method

3.3.4 has() method

3.3.5 set() method

3.3.6 clear() method

3.3.7 PaymentInstrument dictionary

3.3.8 ImageObject dictionary

3.3.9 Convert image objects

3.3.10 Registration Example

4. Can make payment

4.1 Extension to ServiceWorkerGlobalScope

4.1.1 oncanmakepayment attribute

4.2 The CanMakePaymentEvent

4.2.1 respondWith() method

4.2.2 CanMakePaymentEventInit dictionary

4.3 Handling a CanMakePaymentEvent

4.4 Example of handling the CanMakePaymentEvent

4.5 Filtering of Payment Instruments

4.5.1 How to specify capabilities

5. Invocation

5.1 Extension to ServiceWorkerGlobalScope

5.1.1 onpaymentrequest attribute

5.2 The PaymentMethodChangeResponse

5.2.1 error member

5.2.2 total member

5.2.3 modifiers member

5.2.4 paymentMethodErrors member

5.3 The PaymentRequestEvent

5.3.1 topOrigin attribute

5.3.2 paymentRequestOrigin attribute

5.3.3 paymentRequestId attribute

5.3.4 methodData attribute

5.3.5 total attribute

5.3.6 modifiers attribute

5.3.7 instrumentKey attribute

5.3.8 requestBillingAddress attribute

5.3.9 openWindow() method

5.3.10 changePaymentMethod() method

5.3.11 respondWith() method

5.3.12 PaymentRequestEventInit dictionary

5.3.13 MethodData Population Algorithm

5.3.14 Modifiers Population Algorithm

5.4 Internal Slots

5.5 Handling a PaymentRequestEvent

6. Windows

6.1 Open Window Algorithm

6.2 Example of handling the PaymentRequestEvent

7. Response

7.1 PaymentHandlerResponse dictionary

7.1.1 methodName attribute

7.1.2 details attribute

7.2 Change Payment Method Algorithm

7.3 Respond to PaymentRequest Algorithm

8. Security and Privacy Considerations

8.1 Information about the User Environment

8.2 User Consent to Install a Payment Handler

8.3 User Consent before Payment

8.4 Secure Communications

8.5 Authorized Payment Apps

8.6 Supported Origin

8.7 Data Validation

8.8 Private Browsing Mode

9. Payment Handler Display Considerations

10. Dependencies

3.1 Extension to the `ServiceWorkerRegistration` interface

3.2 `PaymentManager` interface

3.2.1 `instruments` attribute

3.2.2 `userHint` attribute

3.3 `PaymentInstruments` interface

3.3.1 `delete()` method

3.3.2 `get()` method

3.3.3 `keys()` method

3.3.4 `has()` method

3.3.5 `set()` method

3.3.6 `clear()` method

3.3.7 `PaymentInstrument` dictionary

3.3.8 `ImageObject` dictionary

4.1 Extension to `ServiceWorkerGlobalScope`

4.1.1 `oncanmakepayment` attribute

4.2 The `CanMakePaymentEvent`

4.2.1 `respondWith()` method

4.2.2 `CanMakePaymentEventInit` dictionary

4.4 Example of handling the `CanMakePaymentEvent`

5.1 Extension to `ServiceWorkerGlobalScope`

5.1.1 `onpaymentrequest` attribute

5.2 The `PaymentMethodChangeResponse`

5.2.1 `error` member

5.2.2 `total` member

5.2.3 `modifiers` member

5.2.4 `paymentMethodErrors` member

5.3 The `PaymentRequestEvent`

5.3.1 `topOrigin` attribute

5.3.2 `paymentRequestOrigin` attribute

5.3.3 `paymentRequestId` attribute

5.3.4 `methodData` attribute

5.3.5 `total` attribute

5.3.6 `modifiers` attribute

5.3.7 `instrumentKey` attribute

5.3.8 `requestBillingAddress` attribute

5.3.9 `openWindow()` method

5.3.10 `changePaymentMethod()` method

5.3.11 `respondWith()` method

5.3.12 `PaymentRequestEventInit` dictionary

6.2 Example of handling the `PaymentRequestEvent`

7.1 `PaymentHandlerResponse` dictionary

7.1.1 `methodName` attribute

7.1.2 `details` attribute