Extension to the ServiceWorkerRegistration interface

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

        partial interface ServiceWorkerRegistration {
          readonly attribute PaymentManager paymentManager;
        };
      

PaymentManager interface

      interface PaymentManager {
        [SameObject] readonly attribute PaymentInstruments instruments;
        [SameObject] readonly attribute PaymentWallets wallets;
                              Promise<boolean>   requestPermission();
      };
      

The PaymentManager is used by payment apps to manage their associated wallets, instruments and supported payment methods.

PaymentInstruments interface

      interface PaymentInstruments {
          Promise<boolean>           delete(DOMString instrumentKey);
          Promise<PaymentInstrument> 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.

PaymentInstrument dictionary

      dictionary PaymentInstrument {
        required DOMString name;
        sequence<ImageObjects> icons;
        sequence<DOMString> enabledMethods;
        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.

enabledMethods member

The enabledMethods member is a list of one or more payment method identifiers of the payment methods 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.

ImageObjects comes from the Web App Manifest specification. Should we reference the definition normatively, or make use of a simpler structure here?

PaymentWallets interface

      interface PaymentWallets {
          Promise<boolean>       delete(DOMString walletKey);
          Promise<PaymentWallet> get(DOMString walletKey);
          Promise<sequence<DOMString>>  keys();
          Promise<boolean>       has(DOMString walletKey);
          Promise<void>          set(DOMString walletKey, PaymentWallet details);
          Promise<void>           clear();
      };
      

Wallets are collections of payment instruments.

Where it appears, the walletKey argument is a unique identifier for the wallet.

PaymentWallet dictionary

      dictionary PaymentWallet {
          required DOMString name;
          sequence<ImageObject> icons;
          required sequence<DOMString> instrumentKeys;
      };
      

name member

The name member is a string that represents the label for this wallet 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 wallet when presented to the user for selection.

instrumentKeys member

The instrumentKeys member is a list of one or more instrumentKeys from PaymentManager.instruments, indicating which PaymentInstrument objects are associated with this Wallet, and should be displayed as being "contained in" the wallet. While it is not generally good practice, there is no restriction that prevents a PaymentInstrument from appearing in more than one Wallet.

Ordering of Payment Handlers

• The user agent MUST favor user-side order preferences (based on user configuration or behavior) over payee-side order preferences.
• The user agent MUST display matching payment handlers in an order that corresponds to the order of supported payment methods provided by the payee, except where overridden by user-side order preferences.
• The user agent SHOULD allow the user to configure the display of matching payment handlers to control the ordering and define preselected defaults.

The second bullet above may be deleted based on PR API issue 481.

The following are examples of payment handler ordering:

• For a given Web site, display payment handlers in an order that reflects usage patterns for the site (e.g., a frequently used payment handler at the top, or the most recently used payment handler at the top).
• Enable the user to set a preferred order for a given site or for all sites.
• If the origin of the site being visited by the user matches the origin of a payment handler, show the payment handler at the top of the list.

The Working Group has discussed two types of merchant preferences related to payment apps: (1) highlighting merchant-preferred payment apps already registered by the user and (2) recommending payment apps not yet registered by the user. The current draft of the specification does not address either point, and the Working Group is seeking feedback on the importance of these use cases. Note that for the second capability, merchants can recommend payment apps through other mechanisms such as links from their web sites.

Display of Instruments

The user agent MUST enable the user to select any displayed instrument.

• At a minimum, we expect user agents to display an icon and label for each matching origin to help the user make a selection.
• In some contexts (e.g., a desktop browser) it may be possible to improve the user experience by offering additional detail to the user. For example, if the user's "bank.com" origin knows about two credit cards (thus, two potential responses to the same payment method "basic-card"), the user agent could display each credit card's brand and the last four digits of the card to remind the user which cards the origin knows about.

In issue 98 there has been push-back to always requiring display of instruments (e.g., on a mobile devices). User agents can incrementally show instruments. Or user agents can return an empty instrumentKey and it becomes the payment app's responsibility to display instruments to the user.

Grouping of Instruments

At times, the same origin may wish to group instruments with greater flexibility and granularity than merely "by origin." These use cases include:

• White label wallets - one origin provides wallet services for multiple vendors
• Multiple user profiles with a single provider (e.g., business wallet vs personal wallet)
• Multiple instruments held with a single provider

A Wallet is a grouping of instruments for display purposes.

To enable developers to build payment apps in a variety of ways, we decouple the registration (and subsequent display) of instruments from how payment handlers respond to a PaymentRequestEvent. However, the user agent is responsible for communicating the user's selection in the event.

Selection of Instruments

Users agents may wish to enable the user to select individual displayed Instruments. The payment handler would receive information about the selected Instrument and could take action, potentially eliminating an extra click (first open the payment app then select the Instrument).

Again related to issue 98: Should we require that, if displayed, individual instruments must be selectable? Or should we allow flexibility that instruments may be displayed, but selecting any one invokes all registered payment handlers? One idea that has been suggested: the user agent (e.g., on a mobile device) could first display the app-level icon/logo. Upon selection, the user agent could display the Instruments in a submenu.

Extension to ServiceWorkerGlobalScope

This specification extends the ServiceWorkerGlobalScope interface.

        partial interface ServiceWorkerGlobalScope {
          attribute EventHandler onpaymentrequest;
        };
        

The PaymentRequestEvent

The PaymentRequestEvent represents a received PaymentRequest.

        [Exposed=ServiceWorker]
        interface PaymentRequestEvent : ExtendableEvent {
          readonly attribute DOMString topLevelOrigin;
          readonly attribute DOMString paymentRequestOrigin;
          readonly attribute DOMString paymentRequestId;
          readonly attribute FrozenArray<PaymentMethodData> methodData;
          readonly attribute PaymentItem total;
          readonly attribute FrozenArray<PaymentDetailsModifier> modifiers;
          readonly attribute DOMString instrumentKey;
          Promise<WindowClient> openWindow(USVString url);
          void respondWith(Promise<PaymentAppResponse>appResponse);
        };
      

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.

For DOM events compatibility, need to add a constructor, and the members of the corresponding dictionary need to match the attributes of the event.

Internal Slots

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

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:

1. Let registration be the ServiceWorkerRegistration corresponding to the PaymentInstrument selected by the user.
2. If registration is not found, reject the Promise that was created by PaymentRequest.show() with a DOMException whose value is "InvalidStateError" and terminate these steps.
3. Invoke the handle functional event algorithm with a ServiceWorkerRegistration of registration and callbackSteps set to the following steps:
   1. Set global to the global object that was provided as an argument.
   2. Create a trusted event, e, that uses the PaymentRequestEvent interface, with the event type paymentrequest, which does not bubble, cannot be canceled, and has no default action.
   3. Set the topLevelOrigin attribute of e to the origin of the top level payee web page.
   4. Set the paymentRequestOrigin attribute of e to the origin of the context where PaymentRequest was initialized.
   5. Set the paymentRequestId attribute of e to the [[\details]].id from the PaymentRequest.
   6. Set the methodData and modifiers attributes of e by executing the MethodData Population Algorithm and Modifiers Population Algorithm respectively.
   7. Set the total attribute of e to a structured clone of the total field on the PaymentDetailsInit from the corresponding PaymentRequest.
   8. Set the instrumentKey attribute of e to the instrumentKey of the selected PaymentInstrument.
   9. Dispatch e to global.
   10. Wait for all of the promises in the extend lifetime promises of e to resolve.
   11. If the payment handler has not provided a PaymentAppResponse as described in , reject the Promise that was created by PaymentRequest.show() with a DOMException whose value "OperationError".

Open Window Algorithm

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

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

1. Let event be this PaymentRequestEvent.
2. Let request be the PaymentRequest that triggered this PaymentRequestEvent.
3. If request.[[\state]] is not "interactive", then return a Promise rejected with a DOMException whose name is "InvalidStateError".
4. Let url be the result of parsing the url argument.
5. If the url parsing throws an exception, return a Promise rejected with that exception.
6. If url is about:blank, return a Promise rejected with a TypeError.
7. Let promise be a new Promise.
8. Run these steps in parallel:
   1. Let newContext be a new top-level browsing context.
   2. Navigate newContext to url, with exceptions enabled and replacement enabled.
   3. If the navigation throws an exception, reject promise with that exception and abort these steps.
   4. If the origin of newContext is not the same as the service worker client origin associated with the payment handler, then:
      1. Reject promise with a DOMException whose name is "SecurityError".
      2. Abort these steps.
   5. Let client be the result of running the capture window client algorithm with newContext as the argument.
   6. If event.[[\windowClient]] is not null, then:
      1. If event.[[\windowClient]].visibilityState is not "unloaded", reject promise with a DOMException whose name is "InvalidStateError" and abort these steps.
   7. Set event.[[\windowClient]] to client.
   8. Resolve promise with client.
9. Return promise.

PaymentAppResponse dictionary

          dictionary PaymentAppResponse {
          DOMString methodName;
          object details;
          };
        

Extention to User Accepts the Payment Request Algorithm

If the Promise is successfully resolved, the user agent MUST run the user accepts the payment request algorithm as defined in [[!PAYMENT-REQUEST-API]], replacing steps 6 and 7 with these steps or their equivalent:

1. Set appResponse to the PaymentAppResponse instance used to resolve the PaymentRequestEvent.respondWith() Promise.
2. If appResponse.methodName is not present or not set to one of the values from PaymentRequestEvent.methodData, run the payment app failure algorithm and terminate these steps.
3. Create a structured clone of appResponse.methodName and assign it to response.methodName.
4. If appResponse.details is not present, run the payment app failure algorithm and terminate these steps.
5. Create a structured clone of appResponse.details and assign it to response.details.

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

      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"
           }
        });
      });
          

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

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.
• Similarly, user agents should not share payment request information with any payment handler until the user has selected that payment handler.

User Consent before Payment

• One goal of this specification is to minimize the user interaction required to make a payment. At the same time, user agents must not permit combinations of configurations that would enable invoking Web sites to invoke payment request and receive payments silently.

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.

Payment App Authenticity

The Web Payments Working Group is also discussing Payment App authenticity; see the (draft) Payment Method Manifest.

Data Validation

• Payees should validate that the data they have received through the paymentRequest API is what they expect (e.g., the total that was paid, etc.).

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.