From eddaa234b109e48966e49211a1f43d7e9e0df375 Mon Sep 17 00:00:00 2001 From: Ian Jacobs Date: Thu, 9 Mar 2017 17:37:55 -0600 Subject: [PATCH 1/7] Structural changes to incorporate https://github.com/w3c/webpayments-payment-apps-api/wiki/Proposal-20170130 --- index.html | 1016 ++++++++++------------------------------------------ 1 file changed, 185 insertions(+), 831 deletions(-) diff --git a/index.html b/index.html index 95dd084..3d01340 100644 --- a/index.html +++ b/index.html @@ -1,7 +1,7 @@ - Payment App API + Payment Handler API @@ -57,7 +57,7 @@ "Zach Koch", "Roy McElmurray" ], - status: "FPWD" + status: "WD" }, "METHOD-IDENTIFIERS": { title: "Payment Method Identifiers", @@ -67,7 +67,7 @@ "Zach Koch", "Roy McElmurry" ], - status: "FPWD" + status: "WD" } } }; @@ -83,18 +83,16 @@
-

Payment Request API [[!PAYMENT-REQUEST-API]] provides - a standard way to initiate payment requests from Web pages and - applications. User agents implementing that API prompt the user - to select a way to handle the payment request, after which - the user agent returns a payment response to the originating site. - This specification adds payment apps - to that user experience. It defines how users - register payment apps with user agents, how user agents present - information about payment apps the user can select to handle the - payment request, how the user selects a payment app, and how communication takes - place between user agents and payment apps to fulfill the requirements of the - underlying Payment Request API.

+

Payment Request API [[!PAYMENT-REQUEST-API]] provides a standard + way to initiate payment requests from Web pages and + applications. User agents implementing that API prompt the user to + select a way to handle the payment request, after which the user + agent returns a payment response to the originating site. This + specification defines capabilities that enable Web applications + to handle payment requests.

+

+ We have changed the title of this specification but left the identifier as-is. We are likely to want to assign it a new URL prior to FPWD. +

The Web Payments Working Group maintains @@ -109,26 +107,32 @@

Introduction

The Web Payments Working Group seeks to streamline payments on the Web to - help reduce payment "abandonment" and make it easier to use + help reduce "shopping cart abandonment" and make it easier to deploy new payment methods on the Web. It has published the Payment Request API [[!PAYMENT-REQUEST-API]] as a standard way to initiate payment - requests from Web pages and applications. This specification adds - payment apps to that user experience. A payment app is software that - enables the user to fulfill a payment request using the user's - preferred payment method.

+ requests from E-Commerce Web sites and applications.

-

This specification defines:

-
    -
  • How users register and unregister payment apps with the user agent (or other "mediator" that implements Payment Request API [[!PAYMENT-REQUEST-API]]).
    • -
  • How the user agent matches payment methods supported by the payee with those enabled in registered payment apps.
    • -
  • How merchants and other payees may recommend payment apps to the user.
    • -
  • How the user agent presents information about payment apps to the user for selection.
    • -
  • How the user agent invokes a payment app, communicates input/response data with it, and returns the response data to the underlying Payment Request API.
    • -
+

A payment app is a Web application that manages + payment requests on behalf of the user by supporting one or more + payment methods. To enable a Web application to handle payment requests, + this specification defines:

+ +
    +
  • How origins (that is: Web sites) request permission to handle payment requests + on the user's behalf.
    • +
  • How origins register their support for different payment methods + with the user agent.
    • +
  • How origins provide information to faciliate the display of + payment app options and selection by the user.
    • +
  • How user agents invoke payment apps selected by the user to make a payment, what data is passed + to the payment apps, and what data is returned after completion of payment.
    • +
-

Payment apps may be implemented in a variety of ways: as Web applications, native operating system applications, - user agent extensions, built-in user agent components, interface-less Web services, or a combination. The scope of this specification is Web-based payment apps, which are implemented as service workers.

+

This specification does not address how software built with + operating-system specific mechanisms (e.g., "native mobile + apps") handle payment requests.

+

This specification defines one class of products: @@ -148,7 +152,7 @@

Introduction

specification's algorithms.

- A conforming Payment App API user agent MUST also be a + A conforming Payment Handler API user agent MUST also be a conforming implementation of the IDL fragments of this specification, as described in the “Web IDL” specification. [[!WEBIDL]] @@ -165,12 +169,6 @@

Introduction

Dependencies

This specification relies on several other underlying specifications.

-
Payment Request API
The terms PaymentRequest, PaymentResponse, @@ -178,13 +176,6 @@

Dependencies

user accepts the payment request algorithm are defined by the Payment Request API specification [[!PAYMENT-REQUEST-API]].
-
HTML5
The terms global object,origin, queue a task, browsing context, top-level browsing @@ -195,38 +186,10 @@

Dependencies

[[!HTML5]].
ECMA-262 6th Edition, The ECMAScript 2015 Language Specification
-
The term Promise - - - is defined by [[!ECMA-262-2015]]. - +
The term Promise is defined by [[!ECMA-262-2015]].
DOM4
-

DOMException and the following DOMException types from [[!DOM4]] are used:

@@ -242,12 +205,6 @@

Dependencies

- @@ -260,14 +217,6 @@

Dependencies

WebIDL
-

The following DOMException types from [[!WEBIDL]] are used:

InvalidStateError The object is in an invalid state
SecurityError The operation is only supported in a secure context
@@ -307,296 +256,76 @@

Dependencies

-

Payment App Model and Design Considerations

-

This section describes the capabilities and limitations of this specification in functional terms.

-
-

General Considerations

-
    -
  • This specification builds on PaymentRequest API.
    • -
  • It defines mechanisms that may be used to support Web-based payment apps. We anticipate that various platforms will offer proprietary alternatives to this specification (e.g., for payment app registration or invocation). Proprietary payment apps lie outside the scope of this specification.
    • -
-
-
-

Decoupling and Trust

-
    -
  • A goal of this system is to decouple the payment methods used to pay from the software (payment apps) that implement those payment methods. By decoupling, merchants (and their payment service providers) can lower the cost of creating a checkout experience, users can have more choice in the software they use to pay, and payment app providers can innovate without imposing an integration burden on merchants.
    • -
  • User choice of payment apps that support a given payment method will depend in part on the willingness of the payment method owner to authorize other parties to implement their payment methods. For example, there may only be one payment app authorized to support a payment method owned by a company, while there may be many apps that support basic credit card payments or credit transfers.
    • -
  • For privacy, we seek to limit information about the user's environment available to merchants without user consent. That includes which payment apps the user has registered. The merchant should not receive information about which payment app the user selected to pay unless the user consents to share that information. (When there is only one payment app for a given payment method that information is already publicly known.)
    • -
  • Although decoupling relieves merchants of implementing some aspects of the checkout experience, one consequence is that they give up some degree of control. This was already the case for some payment methods, but for traditional card payments, merchants (or their PSPs) will be entrusting some portion of data collection to the user agent or third party payment apps.
    • -
  • The design therefore includes support for merchants to recommend payment apps and suggest the display order of payment methods. This specification does not constrain how user agents make use of this information, but provides guidance to user agent developers about taking into account both merchant and user preferences.
    • -
  • The user agent may use this combined preference information to: -
      -
    • Filter payment apps (to matching payment methods)
      • -
    • Order payment apps (according to merchant-specified order)
      • -
    • Display recommended payment apps (according to merchant-specified order)
      • -
    -
    • -
-
-
-

Identification

-
    -
  • A Payment App is identified by a Payment App Identifier (PAI).
    • -
  • This specification defines service-worker based payment apps. The PAI is the service worker's “script URL” that, when dereferenced, returns the code of the service worker.

    See a counter-proposal as part of issue 48

    • -
  • The user agent may make use of the origin information of the PAI in a variety of ways, including: -
      -
    • The origin information could enable user agents to provide the user with useful services when the user is browsing a site with the same origin (e.g., putting that payment app at the top of a list or otherwise highlighted).
      • -
    • For a payment method with an associated origin, the user agent can do some (security) checks by comparing the origin of the payment method and any authorized payment app.
      • -
    -
    • -
-
-
-

Registration and Unregistration

-
    -
  • Registration provides a way for user agents to remain aware of the user's payment apps across transactions.
    • -
  • A payment app that follows this specification must be registered - before it can be used to make a payment. - Note: Registration is not - necessarily a prerequisite to be able to use other types - of payment apps (e.g., native payment apps).
    • -
  • In this specification, payment app registration starts with service - worker registration. Once the user consents to the registration, the - payment app provides information to the browser about enabled payment - methods and associated information; this is used for matching with - payee-accepted payment methods. At this point, the payment app is - registered with the user agent. Note: Registration - does not refer to how the user establishes a - relationship with the payment app provider, for example by setting up an - account with that provider.
    • -
  • We expect registrations to happen at various times (e.g., outside and inside of checkout), and with differing levels of - user consent to modify their configuration within the user agent. In general, explicit consent should not be required - while the user is within the context of the payment request UI. Here are some examples: -
      -
    • Users visiting a Web site (e.g., merchant or bank) may wish to explicitly register payment apps, which would require explicit consent from the user.
      • -
    • When the user selects a recommended payment app the user agent registers the payment app and may do so without additional user action or consent.
      • -
    • When the user installs native payment app, registration could happen either through platform-specific mechanisms or through this standard API, without additional user action beyond installation.
      • -
    -
    • -
  • This specification does require payment apps to be able to respond to user agent queries for updated - registration information. (See issue 36.)
    • -
  • It is important for merchants and users to be able to trust the - authenticity of payment apps. A starting point is to rely on origin information (e.g., if a payment app is registered on a Web site). In contexts where origin binding is unavailable or insufficient, other mechanisms should be considered to help establish authenticity (e.g., origin-bound confirmation of a digital signature of a payment app).
    • -
-
-
- -
    -
  • Payees may recommend payment apps that may be used for a given transaction. In some cases the user may have already registered these payment apps.
    • -
  • To recommend a payment app, a merchant provides a payment app identifier (PAI), name, and icon information. See issue 79 for discussion about how this may be done.
    • -
  • When the user agent presents a recommended (unregistered) payment app for selection by the user, it uses merchant-provided information.
    • -
  • In the case where the user has already registered a recommended payment app, the user agent may use merchant-provided - information to complement information available from the - payment app or to present that payment app for - selection in some special manner. - Note: The Working Group - is still discussing the display of information in the case - of recommended payment apps already registered by the user.
    • -
-
-
-

Payment App Matching and Selection

-
    -
  • When the user invokes the Payment Request API (e.g., by "pushing the Buy button"), the user agent presents a list of "matching" payment apps to the user for selection. Matching payment apps are those recommended by the merchant, and those registered by the user that support the merchant's accepted payment methods (including finer-grain acceptance filters from the merchant).
    • -
  • In the case of a recommended payment app already registered by the user (determined by comparison of payment app identifiers), the user agent may present the app in some special way to highlight the merchant's recommendation.
    • -
  • When the user selects a recommended unregistered payment app, the user agent registers it, using the provided payment app identifier to access the service worker code.
    • -
  • The user agent may offer features to facilitate selection. For example, instead of merely displaying information about a payment app that supports cards, the user agent could display some representation of individual cards stored in the payment app. If the user can select an option directly, that could contribute to reducing the total number of required user actions. User agents might also enable the user to optimize payments using certain payment apps on certain Web sites. User experience optimizations such as these lie outside the scope of this specification.
    • -
-
-
-

Payment App Invocation and Response

-
    -
  • Once the user has selected a payment app, the user agent activates the associated service worker code and provides the payment app with - input data drawn from the Payment Request API.
    • -
  • The user may interact with the payment app in a variety of ways to authorize payment, cancel the transaction, - or carry out other activities supported by the payment app.
    • -
  • This specification defines a means for the user agent to receive a response asynchronously once the user has - authorized payment. The response becomes the response of the Payment Request API.
    • -
  • This specification only describes communication between the - user agent and the payment app. This includes an - asynchronous mechanism for a payment app to return a payment - response to the user agent. This specification does not address communication between the payee server and the payee Web app, or between - the payment app and other parties (e.g., the payment app distributor, or directly to the merchant).
    • -
-
-
+

Overview of Handling Payment Requests

-
-

Definitions

-
-
- -
-

Payment App Implementation Technology

-
-
- user agent-based payment app
-
a payment app that runs in a user agent. User agent-based - payment apps may elect to display a user interface. - This decision is made at runtime, and may vary based - on criteria of the app's choosing (such as how long it has been since the - user last authenticated themselves).
+

In this document we envision the following flow:

-
native payment app
-
a payment app built with the operating system default technology stack that uses non-Web technologies.
-
ignored payment app
-
An app that the user has configured to not be displayed, or that the user agent ignores for security reasons.
-
- payment app identifier
-
- A unique identifier for a payment app (e.g., from a payment - method manifest file). This specification defines these identifiers - as to be service worker scope URLs. As such, they are not - expected to be dereferenced. -
-
payment app window
-
- A service worker WindowClient used by user agent-based - payment apps to interact with the user when doing so is necessary to - complete the payment transaction. -
-
-

- The Web Payments Working Group intends for this specification to apply to any payment app that may be invoked by the user agent, whatever technologies have been used to implement the payment app.

-
-
-

Payment App Registration States

-
-
registered payment app
-
a payment app that is "known" to the user agent for the purposes of the interactions described in this document. +
    -
    - This specification defines a payment app registration mechanism. Other registration mechanisms might co-exist with this one - (e.g., on some platforms there may be a way to register a payment app directly with the operating system).
    -
-
unregistered payment app
-
a payment app that is not known to the user agent, either because it has never been registered, or because it has been unregistered.
+
  • 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 install + a payment app from that origin. The user agent is not required to + prompt the user to grant permission + to the origin for each new supported payment method. A origin's + capabilities may thus evolve without requiring additional user + consent.
    • + +
  • To handle payments, an + origin has at least one and possibly many service worker + registrations. A service worker registration has zero or one + payment handler. +
    • -
    enabled payment app
    -
    A registered payment app with at least one enabled - payment method.
    -
    -
    -
    -

    Payment App Selection States

    -
    -
    matching payment app
    -
    An enabled payment app that: +
  • Registration associates with each payment handler:
      -
    • has at least one enabled payment method that the - payee accepts.
      • - -
    • is not an ignored payment app.
      • +
    • A list of supported payment methods
      • +
    • [Optionally] the conditions under which the handler supports a given payment method, called "capabilities." These are compared to the merchant's capabilities as part of determining whether an origin matches.
      • +
    • Information for organizing the display and grouping of Options + supported by the payment handler.
    -
    • -
    recommended payment app
    -
    a payment app suggested by the payee or user agent that may be used to handle a specific payment request.
    -
    displayed payment app
    -
    A matching payment app or recommended payment app with at least one matching payment method (i.e., presented by the user agent for user selection).
    -
    selected payment app
    -
    the payment app selected by the user to make a payment, but not yet invoked.
    - -
    invoked payment app
    -
    the selected payment app that the user agent has invoked (executed) and passed payment app input data.
    -
    - -
    -
    -

    Payment Method Support

    -
    -
    supported payment method
    -
    a payment method that a payment app has been designed to support. This payment method may or may - not currently be enabled. A payment app MAY support more than one payment method.
    - -
    unsupported payment method
    -
    a payment method that cannot be enabled by a payment app. Updates to a payment app may cause an - unsupported payment method to become supported, or vice-versa.
    - -
    enabled payment method
    -
    a supported payment method that a registered payment app is able to handle. The payment app must have at least - one enabled payment method. -

    - The difference between supported and enabled payment methods is one of design-time vs runtime consideration. - A payment app supports all the payment methods it was designed to support; however at runtime only a subset - may be enabled due to configuration or other runtime requirements that may not have been met for all - supported payment methods. -

    -
    - -
    -
    -
    -

    Payment App Invocation and Response Data

    -
    -
    payment app request
    -
    a request provided to the invoked payment app by the user agent to initiate a payment request. This request is a subset of the Payment Request. -

    - The data passed between the user agent and the payment app will be serialized as JSON data. -

    -
    -
    payment app response
    -
    a response returned by an invoked payment app to the user agent, typically after payment authorization or other action - taken through the payment app. This response, which will vary according to payment method, is then returned to the payee via - the Payment Request API as part of the payment response.
    -
    -
    -
    -
    -

    Overview of Service-Worker-Based Approach

    - -

    In this specification we use service workers - to connect user agents with user agent-based payment apps. We do so for - several reasons:

    - -
      -
    • - Service workers provide a cleanly isolated execution context that allows - the payment app to run with clean separation from the - payee website. -
      • -
    • We can leverage the ways in which service workers already - handle lifecycle management (registration, update, and removal of - payment apps), enable offline use, etc.
      • -
    • We can leverage service worker origins for security, especially - when used in conjunction with origins associated with payment - method identifiers.
      • -
    + -

    - The use of service workers restricts user agent-based payment apps so - that they must run only in secure contexts. The introduction of this - restriction is deliberate, due to the sensitivity of the role that payment - apps play. See issue 24 for information about launching the payment app in a secure context. -

    +
  • When the merchant calls payment request API + (e.g., when the user pushes a button on a checkout page), the + user agent computes a list of matching pyament apps, comparing + those payment methods accepted by the user and those supported + by registered payment handlers.
    • -

    Here is the flow envisioned by this document:

    -
      -
    1. A service worker is registered and associates - payment methods (and associated metadata) with the payment app.
      2. -
    2. When the payment request API is called, the user agent - displays a list of registered service workers associated - with matching payment methods (along with any other payment apps - that may be available to the user agent).
      3. -
    3. When the user selects a user agent-based payment - app, the corresponding service worker is activated, and - it receives a PaymentRequestEvent.
      4. -
    4. Once active, the payment app performs whatever steps are +
    5. When the user selects an Option, the user agent fires the + paymentrequest event in the service worker whose registration + included the payment handler that provided that Option. The + paymentrequest event includes some information from the payment + request object as well as additional information (e.g., origin and + selected Option). +
    6. Once activated, the payment handler performs whatever steps are necessary to authenticate the user, process the payment, and return payment information to the payee. If interaction with the user - is necessary, the payment app can open a payment app - window for that purpose.
      7. -
    7. Finally, once the payment app is finished with its processing, it - resolves a Promise passed to it in the event. This causes the - Promise<PaymentResponse> returned from - PaymentRequest.show() to resolve.
      8. + is necessary, the payment handler can open a window + for that purpose. + +
    8. The user agent receives a response asynchronously once the + user has authorized payment. The response becomes the + response of the Payment Request API.
    + +

    This specification does not address activities outside this flow, including:

    +
      +
    • how the user establishes an account with a payment app provider.
      • +
    • how an origin authenticates a user.
      • +
    • how communication takes place between the payee server and the payee Web application, or between + the payment app and other parties (e.g., the payment app distributor, or directly to the merchant).
      • +
    + +

    Thus, a payment app will rely on many other Web technologies defined + elsewhere for lifecycle management, security, user authentication, + user interaction, and so on.

    +
    +

    - Payment App Registration + Payment Handler Registration

    @@ -626,8 +355,8 @@

    options attribute
    This attribute allows manipulation of payment options associated with a - payment app. To be presented to the user as part of the payment request - flow, payment apps must have at least one registered payment option, and + payment handler. To be presented to the user as part of the payment request + flow, payment handlers must have at least one registered payment option, and that option needs to match the payment methods and required capabilities specified by the payment request.

    Is "options" the right term here? We don't want this to @@ -637,11 +366,11 @@

    wallets attribute
    - This attribute allows payment apps to group payment options together and + This attribute allows payment handlers to group payment options together and provide a name and icon for such a group (e.g., to group together "business account" payment instruments separately from "personal account" payment instruments). The use of this grouping mechanism - by payment apps is completley optional. If payment apps use this + by payment handlers is completley optional. If payment handlers use this grouping mechanism, then matching payment options that do not appear in any groups should still be presented to users by the browser for selection. @@ -664,7 +393,7 @@

    Where it appears, The optionKey parameter is a unique - identifier for the option; it will be passed to the payment app to + identifier for the option; it will be passed to the payment handler to indicate the PaymentAppOption selected by the user.

    TODO: flesh out details after the WG reaches general @@ -708,7 +437,7 @@

    The capabilities member contains a list of payment-method-specific capabilities - that this payment app is capable of supporting for this option. + that this payment handler is capable of supporting for this option. For example, for the basic-card payment method, this object will consist of an object with two fields: one for supportedNetworks, and another for @@ -768,250 +497,13 @@

    TODO

    -

    Registration Example

    -

    The following example shows how to register a user agent-based payment - app:

    - 
    +    
    The following example shows how to register a payment handler:
    
+       
              navigator.serviceWorker.register('/exampleapp.js')
          .then(function(registration) {
            registration.paymentAppManager.options.set(
@@ -1039,7 +531,7 @@ 
    
                enabledMethods: ["basic-card"],
                capabilities: {
                  supportedNetworks:
-                   ['visa','mastercard','americanexpress','discover'],
+                   ['visa','mastercard','amex','discover'],
                  supportedTypes: ['credit','debit','prepaid']
                }
              });
@@ -1073,174 +565,74 @@
    -
    -

    Payment App Matching

    -

    - This section is obsolete. The current proposal involves folding - the payment app matching (based on the entries in - PaymentAppOption.capabilities) into the base Payment Request - specification. -

    -

    - - When the user agent calculates acceptedMethods during the - process of running the steps for the PaymentRequest.show() - method, the means of determining whether a registered payment app - should be made available for user selection is computed by - performing the following steps: -

      -
    1. - Set registeredMethods to an empty set. -
      2. -
    2. - For each PaymentAppOption option in the - payment app's PaymentAppManager.options, add all entries in - option.enabledMethods to - registeredMethods. -
      3. -
    3. - Set requestMethods to a set containing the values - in the supportedMethods value of the - PaymentMethodData from the PaymentRequest - on which show() has been called. -
      4. -
    4. - For each paymentDetailsModifier in - details.modifiers in the - PaymentDetails from the PaymentRequest - on which show() has been called, add all entries in - paymentDteailsModifier.supportedMethods to - requestMethods. -
      5. -
    5. - Set commonMethods to the set union of - paymentMethods and requestMethods. -
      6. -
    6. - If commonMethods is a null set, this payment app is - not considered to be a candidate to handle the - PaymentRequest and terminate these steps. -
      7. -
    7. - If the PaymentAppManifest does not contain a - canHandle attribute, then this payment app is a - candidate for handling the PaymentRequest. Only those - PaymentAppOptions that have enabledMethods - containing at least one member of commonMethods are to be - displayed to the user. Terminate these steps. -
      8. -
    8. - Set methodDataCopy to a deep copy of the - methodData parameter of the PaymentRequest. -
      9. -
    9. - Set detailsCopy to a deep copy of the - details parameter of the PaymentRequest. -
      10. -
    10. - Create an isolated interpreted context, a JavaScript realm that - operates with a globally unique origin. Access to the network must be - disallowed from within this context. -
      11. -
    11. - Populate the realm with a single global function, - canHandle, set to the value of - PaymentAppManifest.canHandle. -
      12. -
    12. - Execute canHandle in the realm, passing - methodDataCopy and detailsCopy as the parameters - to the function. Set returnValue to the return value of - the function. -
      13. -
    13. - If the execution of canHandle results in an exception or - returnValue is not a Sequence of - AvailableOptions, then this - payment app is not considered to be a candidate to handle the - PaymentRequest. Terminate these steps. -
      14. -
    14. - For each AvailableOption of returnValue, - verify that the value of its modifier entry, if - present, is an integer, no smaller than 0, and no larger than the - largest index of PaymentRequest.modifiers sequence. Any - AvailableOption that fails this validation is removed - from the sequence. -
      15. -
    15. - If returnValue has no remaining - AvailableOptions, then this - payment app is not considered to be a candidate to handle the - PaymentRequest. Terminate these steps. -
      16. -
    16. - If processing has reached this point, then the payment app is - a candidate for processing the PaymentRequest. Each - AvailableOption - in returnValue corresponds to a matching - PaymentAppOption that can service the request. If present - the PaymentAppOption.modifier indicates which - PaymentDetailsModifier will be applied by the - corresponding PaymentAppOption. -
      17. -
    - -

    -
    -
    -

    Payment App Selection

    -
    -

    Selectable App Information Display

    -

    - The output of the payment method matching algorithm will be a list of matching payment apps and options from registered - payment apps, and a list of recommended payment apps. The user agent presents this list of displayed payment apps to the user for selection. The user agent MUST enable the user to select any displayed payment app. -

    -
    +
    +

    Payment App and Option Display for Selection

    +

    After applying the matching algorithm defined in Payment Request API, + the user agent offers list of matching payment app to the user to make a selection. Display, ordering, and user experience optimizations by user + agents and payment apps lie outside the scope of this specification.

    +
    -

    Matching Payment Apps

    +

    Ordering of Payment Apps

      -
    • The user agent MUST enable the user to select any matching payment app. Note: See the definition of matching payment app, which excludes payment apps ignored due to user configuration or security issues. Note also that the language here is about enabling selection rather than display — when the user agent displays only a subset of matching payment apps (e.g., the most recently used), the user must still be able to access other matching payment apps.
      • -
    • The user agent MUST enable the user to select any matching payment app options.
    • 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 apps 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 apps to control the ordering and define preselected defaults.
    + +

    The following are examples of user agent ordering of payment apps:

    +
      +
    • For a given Web site, display payment apps in an order that reflects usage patterns for the site (e.g., a frequently used payment app at the top, or the most recently used payment app 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 registered payment app, show the payment app at the top of the list.
      • +
    +
    -

    Recommended Payment Apps

    -
    What is the means by which the payee provides information about recommended payment apps in the call to payment request API? See issue 79.
    +

    Display of Options

    +

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

    +
      -
    • The user agent SHOULD display recommended payment apps and allow configuration to not display recommended payment apps.
      • -
    • The user agent MUST distinguish unregistered recommended payment apps from registered payment apps.
      • -
    • The user agent SHOULD display any recommended apps in the order specified by the payee.
      • +
    • 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.
    + +

    Issue 98. There has been pushback to always requiring display of options (e.g., on a mobile devices). User agents can incrementally show options. Or user agents can return an empty option ID and it becomes the payment app's job to display options to the user.

    +
    -

    User Experience Considerations

    -
    -

    We have identified a number of user experiences that we would like to harmonize. Just a few examples here:

    -
      -
    1. User has no registered payment apps.
      2. -
    2. User has apps with supported but no enabled payment methods.
      3. -
    3. User has apps with supported and enabled payment methods.
      4. -
    4. Merchant wishes to recommend a payment app to the user.
      5. -
    5. User agent wishes to recommend a payment app that supports a payment method for which the user does not - currently have a supporting payment app.
      6. -
    -
    - -

    The following are examples of user agent ordering of selectable payment apps.

    +

    Grouping of Options

    + +

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

      -
    • For a given Web site, display payment apps in an order that reflects usage patterns for the site (e.g., a frequently used payment app at the top, or the most recently used payment app at the top).
      • -
    • Enable the user to set a preferred order for a given site or for all sites.
      • -
    • Display a payment app that is both registered by the user - and recommended at the top of a list.
      • -
    • Display a payment app that is both registered by the user - and corresponds to the origin of the site being visited at the top of a list.
      • +
    • 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 Options for + display purposes.

    + +

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

    + + +
    +

    Selection of Options

    + +

    Users agents may wish to enable the user to select individual displayed Options, in essence launching the payment handler that registered that option. The payment handler would receive information about the selected option and could, in essence, begin to take action (thus eliminating the extra click to open the payment app and then select the option).

    + +

    Issue 98. Should we require that, if displayed, individual Options must be selectable? Or should we allow flexibility that Options 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 Options in a submenu.

    +
    +
    + +

    Payment App Invocation, Display and Response

    @@ -1448,28 +840,6 @@

    -
    -

    Payment App Response

    - The payment app response is conveyed using the following - dictionary: - 
    -      dictionary PaymentAppResponse {
-        DOMString methodName;
-        object details;
-      };
-
    -
    methodName attribute
    -
    - The payment method identifier for the payment method - that the user selected to fulfil the transaction. -
    -
    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. -
    -

    Payment App Invocation

    @@ -1549,11 +919,6 @@

    registration corresponding to the user agent-based payment app selected by the user. -
  • If registration is not found and the selected app - is a recommended app, register the service worker as described - in , skipping user consent and user - agent registration for future use in (steps 9-11). -
  • If registration is not found, reject the Promise that was created by PaymentRequest.show() with a DOMException whose value "InvalidStateError" and @@ -1590,7 +955,7 @@

    • - Payment App Display + Payment App Windows

    An invoked payment app may or may not need to display information @@ -1604,51 +969,34 @@

    opens a window. For subsequent payments in the same session, the payment app (through configuration) performs its duties without opening a window or requiring user interaction. -

    To support scenarios that involve visual display and user interaction, user agents MUST allow payment apps to call the clients.openWindow() method defined in [[!SERVICE-WORKERS]]. Because user agents can determine from event type that the window is part of a payment flow, the user agent SHOULD render the window in a way that is consistent with the flow and not confusing to the user. For example, we recommend that the payment app not be opened in a new browser tab, as this is too dissociated from the checkout context.

    +

    See issue 97 for discussion about opening window in a way that is consistent with payment flow and not confusing to the user. For example, there is consensus that in a desktop environment, a payment handler should not open a window in a new browser tab, as this is too dissociated from the checkout context.

    -

    [[!SERVICE-WORKERS]] expects a user interaction to have occurred in order to open a Window. This user interaction is obvious when the user explicitly selects a payment app to make a payment. However, when user agent or payment app configuration allows payment app invocation without explicit user selection, the user agent MUST consider the paymentrequest event as the relevant user interaction for a clients.openWindow() request.

    -

    User agents SHOULD display the origin of a running payment app to the user.

    -
    -

    Issue 73 asks whether it is possible to close a window open via clients.openWindow() programmatically.

    - -
    -

    The remainder of this section is currently a non-normative explanation of how - the service worker WindowClient class can be used to interact - with users.

    -

    - Upon calling clients.openWindow(), the payment app receives a - Promise which resolves to a WindowClient. For the - purposes of this discussion, we will refer to this - WindowClient as client. The payment app can use - the client.postMessage() method to send messages - to the payment app window. -

    -

    - When a payment app window receives the message event - from the payment app, this event will contain a source - attribute which indicates the payment app's service worker. The payment - app window can then call source.postMessage() to send a - response to the payment app. Once the payment app window has complete its - interaction with the user, it closes the window and uses this - postMessage() call to return information to the payment app. -

    -

    - In order for this approach to work, we have to treat a - paymentrequest as permission to open a popup, which is a formal - property relied up on by [[!SERVICE-WORKERS]]. We need to be careful - that this does not become an end-run around exiting pop-up protections. -

    -

    - Do we want to define a new FrameType for payment app - windows? This requires input from someone with detailed knowledge of - service worker design. -

    -

    Payment App Response

    + + The payment app response is conveyed using the following + dictionary: + 
    +      dictionary PaymentAppResponse {
+        DOMString methodName;
+        object details;
+      };
+
    +
    methodName attribute
    +
    + The payment method identifier for the payment method + that the user selected to fulfil the transaction. +
    +
    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 app through resolution of the Promise provided to the respondWith @@ -1733,12 +1081,16 @@

    Payment App Response

    failures.

    -

    Example of handling the paymentrequest event

    +

    Example of handling the paymentrequest event

    This example shows how to write a service worker that listens to the paymentrequest event. When a payment request event is received, the service worker opens a window in order to interact with the user.

    + +

    Per issue 97, we expect not to use clients.OpenWindow and instead await a proposal for a new openClientWindow method. We will need to update these examples.

    + + 
           self.addEventListener('paymentrequest', function(e) {
@@ -1805,12 +1157,14 @@ 
    Example of handling the paymentrequest event

    +

    Security and Privacy Considerations

    Information about the User Environment

      -
    • The API does not share information about the user's registered payment methods or payment apps with the payee. The only information that is shared is the result of user selection.
      • +
    • The API does not share information about the user's registered payment apps. Information from payment apps is only shared with the payee with the consent of the user.
      • +
    • Similarly, user agents should not share payment request information with any payment app until the user has selected that payment app.
    @@ -1829,7 +1183,7 @@

    Secure Communications

    Payment App Authenticity

      -
    • To avoid problems such as phishing-type attacks on payee sites, we want to be able to ensure the authenticity of payment apps. In general we expect to rely on origin information for establishing payment app authenticity. In contexts where payment apps are referenced other than on their origin, we are considering additional measures to help establish authenticity. Examples: validate a digital signature prior to launching a recommended app or a registered payment app without associated origin information.
      • +
    • To avoid problems such as phishing-type attacks on payee sites, we want to be able to ensure the authenticity of payment apps. In general we expect to rely on origin information for establishing payment app authenticity. In contexts where payment apps are referenced other than on their origin, we are considering additional measures to help establish authenticity.
    • Note: More work is required on good practice so that it is easy for users to use trusted apps (e.g., white listing by the browser or merchant) and hard to use risky apps (e.g., warnings to the user and explicit user overrides as done today with untrusted certificates).
    From f9e96fd7e5da1d5965661fd504eda3c7acb388c0 Mon Sep 17 00:00:00 2001 From: Ian Jacobs Date: Thu, 9 Mar 2017 17:40:18 -0600 Subject: [PATCH 2/7] markup bug fix --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 3d01340..3cdd80f 100644 --- a/index.html +++ b/index.html @@ -1081,7 +1081,7 @@

    Payment App Response

    failures.

    -

    Example of handling the paymentrequest event +

    Example of handling the paymentrequest event

    This example shows how to write a service worker that listens to the paymentrequest event. When a payment request event is received, the From e5c527159711203c124ef28c3eca7e2f74594468 Mon Sep 17 00:00:00 2001 From: Ian Jacobs Date: Fri, 10 Mar 2017 16:06:33 -0600 Subject: [PATCH 3/7] Cleanup --- index.html | 69 ++++++++++++++++++++++++------------------------------ 1 file changed, 30 insertions(+), 39 deletions(-) diff --git a/index.html b/index.html index 3cdd80f..b9f7bb3 100644 --- a/index.html +++ b/index.html @@ -1,4 +1,4 @@ - +` Payment Handler API @@ -118,14 +118,13 @@

    Introduction

    this specification defines:

      -
    • How origins (that is: Web sites) request permission to handle payment requests +
    • How origins (i.e., Web sites) request permission to handle payment requests on the user's behalf.
    • How origins register their support for different payment methods with the user agent.
    • How origins provide information to faciliate the display of - payment app options and selection by the user.
      • -
    • How user agents invoke payment apps selected by the user to make a payment, what data is passed - to the payment apps, and what data is returned after completion of payment.
      • + payment options for selection by the user. +
    • How user agents invoke and exchange data with payment handlers from an origin.

    This specification does not address how software built with @@ -279,24 +278,27 @@

    Overview of Handling Payment Requests

  • Registration associates with each payment handler:
      -
    • A list of supported payment methods
      • -
    • [Optionally] the conditions under which the handler supports a given payment method, called "capabilities." These are compared to the merchant's capabilities as part of determining whether an origin matches.
      • +
    • A list of supported payment methods.
      • +
    • [Optionally] the conditions under which the handler supports a given payment method; these "capabilities" play a role in matching computations.
    • Information for organizing the display and grouping of Options supported by the payment handler.
    • -
  • When the merchant calls payment request API +
  • When the merchant calls Payment Request API (e.g., when the user pushes a button on a checkout page), the user agent computes a list of matching pyament apps, comparing - those payment methods accepted by the user and those supported - by registered payment handlers.
    • + the payment methods accepted by the user with those supported + by registered payment handlers. For payment methods that support + additional filtering, merchant and payment app capabilities are + compared as part of determining whether there is a match.
  • When the user selects an Option, the user agent fires the paymentrequest event in the service worker whose registration included the payment handler that provided that Option. The - paymentrequest event includes some information from the payment - request object as well as additional information (e.g., origin and + paymentrequest event includes some information from the PaymentRequest + (defined in [[!PAYMENT-REQUEST-API]]) + as well as additional information (e.g., origin and selected Option).
  • Once activated, the payment handler performs whatever steps are necessary to authenticate the user, process the payment, and return @@ -305,8 +307,8 @@

    Overview of Handling Payment Requests

    for that purpose.
  • The user agent receives a response asynchronously once the - user has authorized payment. The response becomes the - response of the Payment Request API.
    • + user has authorized payment. The response becomes the + PaymentResponse (of [[!PAYMENT-REQUEST-API]]).

    This specification does not address activities outside this flow, including:

    @@ -370,7 +372,7 @@

    provide a name and icon for such a group (e.g., to group together "business account" payment instruments separately from "personal account" payment instruments). The use of this grouping mechanism - by payment handlers is completley optional. If payment handlers use this + by payment handlers is completely optional. If payment handlers use this grouping mechanism, then matching payment options that do not appear in any groups should still be presented to users by the browser for selection. @@ -568,8 +570,9 @@

    Payment App and Option Display for Selection

    After applying the matching algorithm defined in Payment Request API, - the user agent offers list of matching payment app to the user to make a selection. Display, ordering, and user experience optimizations by user - agents and payment apps lie outside the scope of this specification.

    + the user agent displays a list of matching payment app for the user to make + a selection. This specification includes a limited number of display + requirements; most user experience details are left to user agents.

    Ordering of Payment Apps

    @@ -579,7 +582,7 @@

    Ordering of Payment Apps

  • The user agent SHOULD allow the user to configure the display of matching payment apps to control the ordering and define preselected defaults.
    • -

    The following are examples of user agent ordering of payment apps:

    +

    The following are examples of payment app ordering:

    • For a given Web site, display payment apps in an order that reflects usage patterns for the site (e.g., a frequently used payment app at the top, or the most recently used payment app at the top).
    • Enable the user to set a preferred order for a given site or for all sites.
      • @@ -636,10 +639,10 @@

      Selection of Options

      Payment App Invocation, Display and Response

      - Once the user has selected a payment app, the user agent is - responsible for preparing a payment app request, invoking the - payment app, providing the request data to the payment app, and - returning the payment app response through the Payment Request API. + Once the user has selected a payment app, the user agent + fires a paymentrequest event with a Payment App Request, + and uses the subsequent Payment App Response to create a PaymentReponse + for [[!PAYMENT-REQUEST-API]].

      Payment App Request

      @@ -703,6 +706,9 @@

      Payment App Request

      payment app registration. + +

      See issue 91 for discussion about the inclusion of line items in the Payment App Request.

      +

      Method Data Population Algorithm @@ -842,19 +848,6 @@

      Payment App Invocation

      -

      - Payment apps are invoked when a payee requests a payment - by calling PaymentRequest.show() and the user selects a - payment app (or has one implicitly selected by previously established - user preferences). If the user selects a user agent-based payment - app to service the request, the service worker corresponding - to that application receives an event with the - PaymentAppRequest containing information about the payment - being requested. The event also contains a function that allows the - payment app to provide a payment response back to the - payee. This process is formally described in the following - sections. -

      Extension to ServiceWorkerGlobalScope @@ -1182,10 +1175,8 @@

      Secure Communications

      Payment App Authenticity

      -
        -
      • To avoid problems such as phishing-type attacks on payee sites, we want to be able to ensure the authenticity of payment apps. In general we expect to rely on origin information for establishing payment app authenticity. In contexts where payment apps are referenced other than on their origin, we are considering additional measures to help establish authenticity.
        • -
      • Note: More work is required on good practice so that it is easy for users to use trusted apps (e.g., white listing by the browser or merchant) and hard to use risky apps (e.g., warnings to the user and explicit user overrides as done today with untrusted certificates).
        • -
      +

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

      Data Validation

      From 4d152e7e00fd2f80c9b71531fce2a8fc50b6491b Mon Sep 17 00:00:00 2001 From: Ian Jacobs Date: Fri, 10 Mar 2017 16:20:07 -0600 Subject: [PATCH 4/7] more cleanup --- index.html | 24 +++++++++++------------- 1 file changed, 11 insertions(+), 13 deletions(-) diff --git a/index.html b/index.html index b9f7bb3..902bd56 100644 --- a/index.html +++ b/index.html @@ -313,10 +313,9 @@

      Overview of Handling Payment Requests

      This specification does not address activities outside this flow, including:

        -
      • how the user establishes an account with a payment app provider.
        • +
      • 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 - the payment app and other parties (e.g., the payment app distributor, or directly to the merchant).
        • +
      • how communication takes place between the payee server and the payee Web application, or between the payment app origin and other parties.

      Thus, a payment app will rely on many other Web technologies defined @@ -570,7 +569,7 @@

      Payment App and Option Display for Selection

      After applying the matching algorithm defined in Payment Request API, - the user agent displays a list of matching payment app for the user to make + the user agent displays a list of matching payment apps for the user to make a selection. This specification includes a limited number of display requirements; most user experience details are left to user agents.

      @@ -628,7 +627,7 @@

      Grouping of Options

      Selection of Options

      -

      Users agents may wish to enable the user to select individual displayed Options, in essence launching the payment handler that registered that option. The payment handler would receive information about the selected option and could, in essence, begin to take action (thus eliminating the extra click to open the payment app and then select the option).

      +

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

      Issue 98. Should we require that, if displayed, individual Options must be selectable? Or should we allow flexibility that Options 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 Options in a submenu.

      @@ -639,7 +638,7 @@

      Selection of Options

      Payment App Invocation, Display and Response

      - Once the user has selected a payment app, the user agent + Once the user has selected an Option, the user agent fires a paymentrequest event with a Payment App Request, and uses the subsequent Payment App Response to create a PaymentReponse for [[!PAYMENT-REQUEST-API]]. @@ -703,7 +702,7 @@

      Payment App Request

      This attribute indicates the PaymentAppOption selected by the user. It corresponds to the id field provided during - payment app registration. + registration.
      @@ -847,7 +846,7 @@

      -

      Payment App Invocation

      +

      Invocation

      Extension to ServiceWorkerGlobalScope @@ -904,12 +903,11 @@

      Upon receiving a payment request by way of PaymentRequest.show() and subsequent user selection of a - user agent-based payment app, the user agent MUST run - the following steps or their equivalent: + payment app, the user agent MUST run the following steps or their equivalent:

      1. Let registration be the service worker - registration corresponding to the user agent-based payment app + registration corresponding to the payment app selected by the user.
      2. If registration is not found, reject the Promise that @@ -1170,7 +1168,7 @@

        User Consent before Payment

        Secure Communications

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

      @@ -1187,7 +1185,7 @@

      Data Validation

      Private Browsing Mode

        -
      • When the Payment Request API is invoked in a "private browsing mode," the user agent should launch user agent-based payment apps 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 payment app or re-enter payment instrument details.
        • +
      • When the Payment Request API is invoked in a "private browsing mode," the user agent should launch payment apps 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 payment app or re-enter payment instrument details.
      From e44844e9d2eed53d61a25eb0585dffda94e6f044 Mon Sep 17 00:00:00 2001 From: Ian Jacobs Date: Fri, 10 Mar 2017 16:21:29 -0600 Subject: [PATCH 5/7] sigh; char added --- index.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.html b/index.html index 902bd56..b440d35 100644 --- a/index.html +++ b/index.html @@ -1,4 +1,4 @@ -` + Payment Handler API From a4b915565a5bcd964bbe25ff33b6886f36ec7b8c Mon Sep 17 00:00:00 2001 From: Ian Jacobs Date: Tue, 14 Mar 2017 16:55:43 -0500 Subject: [PATCH 6/7] Add bit about display and goruping of options --- index.html | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/index.html b/index.html index b440d35..8bc5234 100644 --- a/index.html +++ b/index.html @@ -287,19 +287,23 @@

      Overview of Handling Payment Requests

    • When the merchant calls Payment Request API (e.g., when the user pushes a button on a checkout page), the - user agent computes a list of matching pyament apps, comparing + user agent computes a list of matching payment apps, comparing the payment methods accepted by the user with those supported by registered payment handlers. For payment methods that support additional filtering, merchant and payment app capabilities are - compared as part of determining whether there is a match.
      • + compared as part of determining whether there is a match. + +
    • The user agent displays matching payment apps, displaying + and grouping Options according to information (labels and + icons) provided at registration or otherwise available from + the Web app.
    • When the user selects an Option, the user agent fires the paymentrequest event in the service worker whose registration included the payment handler that provided that Option. The paymentrequest event includes some information from the PaymentRequest (defined in [[!PAYMENT-REQUEST-API]]) - as well as additional information (e.g., origin and - selected Option). + as well as additional information (e.g., origin and selected Option).
    • Once activated, the payment handler performs whatever steps are necessary to authenticate the user, process the payment, and return payment information to the payee. If interaction with the user From 74e9aff63b21ae0809b17d0ae787673f02d8eafa Mon Sep 17 00:00:00 2001 From: Ian Jacobs Date: Tue, 14 Mar 2017 21:44:18 -0500 Subject: [PATCH 7/7] More attempts to use payment handler instead of payment app --- index.html | 76 +++++++++++++++++++++++++++--------------------------- 1 file changed, 38 insertions(+), 38 deletions(-) diff --git a/index.html b/index.html index 8bc5234..e5848f5 100644 --- a/index.html +++ b/index.html @@ -263,8 +263,8 @@

      Overview of Handling Payment Requests

    • 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 install - a payment app from that origin. The user agent is not required to + a user visiting a retail or bank site may be prompted to register + a payment handler from that origin. The user agent is not required to prompt the user to grant permission to the origin for each new supported payment method. A origin's capabilities may thus evolve without requiring additional user @@ -287,13 +287,13 @@

      Overview of Handling Payment Requests

    • When the merchant calls Payment Request API (e.g., when the user pushes a button on a checkout page), the - user agent computes a list of matching payment apps, comparing + user agent computes a list of matching payment handlers, comparing the payment methods accepted by the user with those supported by registered payment handlers. For payment methods that support - additional filtering, merchant and payment app capabilities are + additional filtering, merchant and payment handler capabilities are compared as part of determining whether there is a match.
      • -
    • The user agent displays matching payment apps, displaying +
    • The user agent displays matching payment handlers, displaying and grouping Options according to information (labels and icons) provided at registration or otherwise available from the Web app.
      • @@ -319,10 +319,10 @@

      Overview of Handling Payment Requests

      • 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 the payment app origin and other parties.
        • +
      • how communication takes place between the payee server and the payee Web application, or between a payment app origin and other parties.
      -

      Thus, a payment app will rely on many other Web technologies defined +

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

      @@ -571,25 +571,25 @@

      -

      Payment App and Option Display for Selection

      +

      Origin and Option Display for Selection

      After applying the matching algorithm defined in Payment Request API, - the user agent displays a list of matching payment apps for the user to make + the user agent displays a list of matching origins for the user to make a selection. This specification includes a limited number of display requirements; most user experience details are left to user agents.

      -

      Ordering of Payment Apps

      +

      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 apps 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 apps to control the ordering and define preselected defaults.
        • +
      • 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 following are examples of payment app ordering:

      +

      The following are examples of payment handler ordering:

        -
      • For a given Web site, display payment apps in an order that reflects usage patterns for the site (e.g., a frequently used payment app at the top, or the most recently used payment app at the top).
        • +
      • 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 registered payment app, show the payment app at the top of the list.
        • +
      • 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.
      @@ -602,7 +602,7 @@

      Display of Options

    • 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.

    -

    Issue 98. There has been pushback to always requiring display of options (e.g., on a mobile devices). User agents can incrementally show options. Or user agents can return an empty option ID and it becomes the payment app's job to display options to the user.

    +

    Issue 98. There has been pushback to always requiring display of options (e.g., on a mobile devices). User agents can incrementally show options. Or user agents can return an empty option ID and it becomes the payment app's responsibility to display options to the user.

    @@ -640,7 +640,7 @@

    Selection of Options

    -

    Payment App Invocation, Display and Response

    +

    Payment Handler Invocation, Display and Response

    Once the user has selected an Option, the user agent fires a paymentrequest event with a Payment App Request, @@ -726,7 +726,7 @@

  • For each PaymentAppOption option in the - payment app's PaymentAppManager.options, add all entries in + payment handler's PaymentAppManager.options, add all entries in option.enabledMethods to registeredMethods.
    • @@ -791,7 +791,7 @@

  • For each PaymentAppOption option in the - payment app's PaymentAppManager.options, add all + payment handler's PaymentAppManager.options, add all entries in option.enabledMethods to registeredMethods.
    • @@ -900,18 +900,18 @@

    respondWith method
    - This method is used by the payment app to provide a + This method is used by the payment handler to provide a PaymentAppResponse when the payment successfully completes.

    Upon receiving a payment request by way of PaymentRequest.show() and subsequent user selection of a - payment app, the user agent MUST run the following steps or their equivalent: + payment handler, the user agent MUST run the following steps or their equivalent:

    1. Let registration be the service worker - registration corresponding to the payment app + registration corresponding to the payment handler selected by the user.
    2. If registration is not found, reject the Promise that @@ -938,7 +938,7 @@

    3. Dispatch e to global.
    4. Wait for all of the promises in the extend lifetime promises of e to resolve.
      5. -
    5. If the payment app has not provided a payment app +
    6. If the payment handler has not provided a payment app response as described in , reject the Promise that was created by PaymentRequest.show() with a @@ -950,23 +950,23 @@

    - Payment App Windows + Payment Handler Windows

    -

    An invoked payment app may or may not need to display information +

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

    + payment handler displays include:

      -
    • The payment app opens a window for the user to provide an authorization code.
      • -
    • The payment app 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 app - opens a window. For subsequent payments in the same session, the payment app (through configuration) performs its duties without opening a window or requiring user interaction.
      • +
    • 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.

    See issue 97 for discussion about opening window in a way that is consistent with payment flow and not confusing to the user. For example, there is consensus that in a desktop environment, a payment handler should not open a window in a new browser tab, as this is too dissociated from the checkout context.

    -

    User agents SHOULD display the origin of a running payment app to the user.

    +

    User agents SHOULD display the origin of a running payment handler to the user.

    @@ -993,7 +993,7 @@

    Payment App Response

    - The user agent receives a successful response from the payment app + 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 dictionary. The application is expected to resolve the Promise with a @@ -1009,7 +1009,7 @@

    Payment App Response

    • - Letting the user try again, with the same payment app or with a + Letting the user try again, with the same payment handler or with a different one.
    • @@ -1110,9 +1110,9 @@

      Example of handling the paymentrequest event

      });

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

      - 
      +    
       <html> <body> <form id="form">
 <table>
   <tr><th>Cardholder Name:</th><td><input name="cardholderName"></td></tr>
@@ -1158,8 +1158,8 @@ 
      Security and Privacy Considerations
      
   
      
     
      Information about the User Environment
      
     
        
-      
      • The API does not share information about the user's registered payment apps. Information from payment apps is only shared with the payee with the consent of the user.
        • 
-      
      • Similarly, user agents should not share payment request information with any payment app until the user has selected that payment app.
        • 
+      
      • 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.
        • 
     
      
   
      
   
      
@@ -1189,7 +1189,7 @@ 
      Data Validation
      
   
      
     
      Private Browsing Mode
      
     
        
-      
      • When the Payment Request API is invoked in a "private browsing mode," the user agent should launch payment apps 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 payment app or re-enter payment instrument details.
        • 
+      
      • 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.
        •