Payment Handler

[rsolomakhin]

こんにちはTAG！

I'm requesting a TAG review of:

• Name: Payment Handler
• Specification URL: https://w3c.github.io/payment-handler/
• Example code: https://rsolomakhin.github.io/pr/apps/ , https://bobpay.xyz/
• Tests: https://github.com/w3c/web-platform-tests/tree/master/payment-handler
• Primary contacts: @rsolomakhin @marcoscaceres @zkoch @DurgaTheHutt @madmath @anthonyvd @gogerald @romandev

Further details:

• Relevant time constraints or deadlines: Would it be possible to review this by the 1st of March, 2018?

You should also know that...

We'd prefer the TAG provide feedback as:

• leave review feedback as a comment in this issue and @-notify @rsolomakhin @marcoscaceres @zkoch @DurgaTheHutt @madmath @anthonyvd @gogerald @romandev

[dbaron]

@rsolomakhin Is there an explainer somewhere?

[rsolomakhin]

@dbaron : Please take a look at https://docs.google.com/document/d/1wM9b3szNH4-w0tpIefjLYSGNtyjLr31Q4ARNTB52bJ0

[dbaron]

One issue that's probably worth looking into is that this draft has yet another way to specify icons (compare it to what Web App Manifest has or what the Notifications API has). Should the icon mechanism here be more similar to what Web App Manifest does? Or should, perhaps, even more of the registration mechanism of payment instruments depend on Web App Manifest?

[rsolomakhin]

@dbaron: Excellent point! The specification makes the usage of instrument icons optional. From what I understand, Firefox plans to display each instrument individually together with their icons. Note that these icons might be different from what's in the web app manifest. A web app manifest for MyBank.com would have a bank logo, but the instrument icon for "Visa*1234" would be a VISA logo.

Chrome, on the other hand, plans to display a payment handler as whole, without breaking it up into instruments. As such, Chrome will use name and icon from the web app manifest of the page that registers the payment handler. The web app manifest icons are downloaded and stored at the time of the payment handler registration. See https://rsolomakhin.github.io/pr/apps/ for demonstrations of web app manifest usage for payment handlers in Chrome. (The feature is enabled by default in Canary.) There're a few demos with intentionally missing web app manifests or icons. If you open up the dev tools console, you will see warnings about the missing iconography in those cases.

Note that Chrome still uses the capabilities and supportedMethods fields of instruments to match payment handlers to PaymentRequest calls, so instruments are still useful to us.

[tantek]

@dbaron agreed yet-another-way to specify an icon, as there's already a huge proliferation problem for icon markup.

I found this similar issue: w3c/payment-handler#233 but no actual issue on "Yet another way to specify an icon" or perhaps "Clarify instrument icon vs webapp manifest icon" for how should webdevs (and browsers that implement this spec) use each where in UI?

w3c/manifest#652 seems to cover the broader "duplication with webapp manifest" issue, @marcoscaceres comment w3c/manifest#652 (comment) specifically re: icons.

[foolip]

There's an Intent to Ship: Payment Handler on blink-dev. Any ETA on when this review will be "done"?

[torgo]

So... we are just reviewing this today unfortunately. We have had a bit of a backlog. We will try to get some feedback within next few weeks.

[dbaron]

So I've read through the spec, thought about it a bit, and talked to a few colleagues about it. While I don't consider this a complete review, I've done a bit of thinking at this point, and come up with five architectural questions that I think are worth examining here:

1. Does this API make the right tradeoffs between permissions, extensibility, and user confusion? In particular, we'd like the web to allow payment processors and payment methods that we don't know about, since allowing more competition is likely to benefit merchants and users. But at the same time we should consider whether it's a problem if either the merchants or the users to be confused about what payment systems they're using. (see overview, points 1 and 5)

2. Does this API make the right tradeoffs in terms of running the necessary level of detail through the API to allow browsers to present users with trusted payment user interface (or, if needed, giving the user the right security indicators about the level of trust) versus letting the payment handler customize what it needs? (see overview, point 7)

3. Does it allow both user-agents and merchants to make choices about whether the user should only be presented with already-configured payment mechanisms, or given the option to set up new ones? (It doesn't seem to allow setup as part of the overview.) Or is it at least extensible to allow this in the future?

4. Does it make the right tradeoffs about reusing pieces of technology already present in the platform versus inventing new things?

5. Does this specification introduce new mechanisms for communication between origins that need to be considered carefully?

For background, this spec has a close relationship to three other specs that I'm aware of: Payment Request API, Payment Method Identifiers, and Payment Method Manifest. (While this specification doesn't reference Payment Method Manifest, the Payment Method Manifest spec imposes requirements on users of certain Payment Method Identifiers, though I'd note that it's odd that these requirements ("the requirement that every payment method whose identifier is URL-based will provide a payment method manifest file in JSON format") aren't in the Payment Method Identifiers spec.)

The high-level structure of the spec, which I'm writing down since I've been tending to confuse myself if I don't, is that a service worker (together with the code that registers it) can be payment handler if it has instruments registered; it can have multiple instruments, which in turn can each support multiple payment methods. I had thought that this would mean that something like a credit card would be a payment instrument; however, the userHint property (described as intending to be things like "**** 1234" to remind a user of a card) is associated with the entire payment handler.

Extensibility, permissions, and UI

So delving a little bit deeper into point (1) above:

It's not clear to me how browsers plan to explain to users what installing a payment handler means. In particular, will the user need to make judgments about what powers the payment handler has, or only about whether the user wants to allow a particular site to install something that handles payments? (Will the payment instruments then later be identified with that site when it's time for the user to choose them, perhaps?) I think the norm today is that payers think primarily in terms of payment instruments and a little bit in terms of what mechanisms that card supports (e.g., I have this card, and maybe that the card supports both credit and debit), whereas payees (merchants) also think in terms of payment methods or processors since they have different costs to the merchant. So perhaps the user permission issue isn't a big deal, assuming that the intent is the simple form of the question and there's a belief that that form is sufficient. But if there's a need for the user to understand more detail, then it's not clear to me that this system gives that detail in any form that can be presented to the user as reliable or trustworthy information.

I suppose then there's the related question of whether the identifiers pose risks to merchants. Presumably if somebody installs a malicious payment handler as a way to cheat merchants, claiming to support a particular payment method that the merchant wants, the expected way to deal with this is that the payment processor and the merchant involved need to validate all the data sufficiently to ensure that they're getting the expected payment. Given that the merchant can't trust any security checking that the browser does anyway (even if the browser does end up verifying something based on the payment method manifest connected to the identifier), this seems like it has to be the answer. Perhaps that should be called out a little more clearly in the section on security considerations?

Detail and user interface

Based on the user interface I've seen so far, I'm more concerned about point (2). The current experimental Chrome user interface includes UI from the payment handler within what looks like privileged browser UI. For example, if you:

• go to chrome://flags and enable "Service Worker payment apps"
• go to BobPay and click "Install BobPay Web Payment App" in the lower right
• go to the BobPay Demo from the list of demos
• click the "Buy" button
• click the "Pay" button in the browser chrome sheet that pops down

you'll currently end up seeing Web Content inside browser chrome UI (screenshot courtesy @marcoscaceres via mozilla/standards-positions#23 (comment)):

This is explicitly described in the 2.1 Handling a Payment Request which says:

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

This UI raises a number of questions. Does this UI from the payment handler's origin that is shown within the browser chrome have the usual permissions that web pages have, or more, or less? What happens if it asks for permissions that require prompts? Does it share things like permissions and storage with regular tabs from the origin, or are they somehow different? Does it influence computations that depend on whether and how long the user is interacting with a page from the origin? Does it honor settings like private browsing mode? And there are many more questions like this. It's concerning because it's a new sort of UI, adding new complexity in an area where user interface is closely connected to origins and to the parts of the web's security model that we hope the web's users will understand.

It's not clear to me that this sort of user interface will be accepted across browser vendors; in fact I suspect it will not be. That raises the next question: why is this user interface needed? And would passing additional data through the payment handler API allow the browser to present the necessary information to the user in a way that could avoid this user interface... or at least avoid every having to present it in privileged UI rather than as a regular web page? If additional API surface is needed, should it be added?

Configured vs. new payment mechanisms?

On point (3), it doesn't seem like this specification offers a mechanism for the user to configure a new payment handler if none are currently available. However, it seems at least worth making sure the system could be extended to allow that if it becomes desirable. It seems to me that payment method manifest would allow such an extension, since the payment request contains payment method identifiers that should allow locating a payment method manifest. So I don't think this is something to worry about, but I wanted to check that others agree.

Reusing existing pieces of the platform vs. making new ones?

There are a number of places where parts of this specification are closely modeled on existing mechanisms in the ServiceWorker specification. That seems like a good thing.

I'm a little worried, however, about the proliferation of manifest formats, and (as mentioned above) the proliferation of ways of specifying icons.

Communication between origins?

One other question I had ((5) above) was whether this introduces new mechanisms for communication between origins that don't exist today. In particular, I'm wondering about the ability of the CanMakePayment event to communicate with a payment handler installed by another origin (without triggering any immediate network traffic). It's not clear to me whether this is something Service Workers allow today (I'm not particularly knowledgable on handling of cross-origin requests by Service Workers) or whether there are other features of the Web that already allow similar things. This is a concern that may be trivial to refute by demonstrating that it's something already allowed, but if it's not, it may be worth thinking about more closely.

Other

A few other details:

• I'm slightly concerned that 2.3 Relation to Other Types of Payment Apps talks about connections to native payment apps, yet I'm not aware of a spec that explains how such apps relate to payment method identifiers and payment method manifests.
• It might be worth discussing PaymentManager.requestPermission() and its relationship to disputes over the Permissions API. It's also poor form for a "NOTE" (at the start of the section) to modify the requirements in normative text (item (4) in the list); instead the normative text should be modified accordingly.
• the issue of specifying icons discussed above
• I wonder if the PaymentInstruments.get() method should resolve to null rather than undefined when there isn't an instrument. I think at the very least WebIDL supports this better (Promise<PaymentInstrument?> rather than Promise<any>) though I'm not sure what conventions are. It seems like some specs go both ways, e.g., Clients.get() and ServiceWorkerContainer.getRegistration() resolve to undefined, but Clients.openWindow(), CredentialsContainer.get(), and PushManager.getSubscription() resolve to null. I suspect the design principles document ought to say something about undefined vs null, although maybe there's a subtle semantic difference here that I'm missing.
• step 1 of the set() method needs to specify needs to specify the permission descriptor type (i.e., which permission) (and also the link is broken)
• is it ok that step 3 of the set() method returns a promise that's already rejected?
• is it ok that step 6 of the set() method sets an internal slot on a dictionary? What does that mean, especially since the dictionary is then stored into what is described only informally as a collection.
• Given what step 3 of the keys() method says, step 8 of the set() method should probably say append rather than insert.
• there are a number of places (e.g., PaymentInstrument.name) where this specification has APIs involving text that is to be presented to the user. Are there going to be issues with localization or internationalization with this? That is, is the assumption that localization can be done prior to registration of the service worker safe, and is the assumption that only plain text will be sufficient for internationalization correct?
• The Convert image objects section seems to repeatedly say "return an empty Sequence of ImageObject" (which means that the entire algorithm returns an empty list because of the failure of just one of the images) when it means to say continue.
• ExtendableEvent and ExtendableEventInit aren't hyperlinked, but should be.
• Is CanMakePaymentEvent.respondWith intended to integrate with the extend lifetime promises of the ExtendableEvent? The definition seems rather short. See, for example, the definition of FetchEvent.respondWith(), or even PaymentRequestEvent.respondWith().
• steps 2 ("Let registration be a ServiceWorkerRegistration.") and 3 ("If registration is not found, terminate these steps.") of 4.3 Handling a CanMakePaymentEvent don't seem to make sense together. It seems like something ought to be describing which service workers should have the event dispatched, perhaps by integrating with 4.5 Filtering of Payment Instruments?
• the defitions of topLevelOrigin and paymentRequestOrigin should probably refer to the serialization of the origin. (5.4 Handling a PaymentRequestEvent gets this right.)
• should the Open Window Algorithm also integrate with the extend lifetime promises?
• in the Open Window Algorithm, the reference to being "triggered by user activation" seems like it might be misplaced; do the normal uses of this API actually meet this definition?
• the Open Window Algorithm doesn't seem to allow the behavior suggested in the earlier note: "A single payment handler SHOULD NOT be allowed to open more than one client window using this method." It seems like it should give the UA rather more discretion about when opening windows is allowed (likely even more than the note allows).
• The Open Window Algorithm should probably be clearer about what its parameters are (both in the algorithm and at its caller).
• 8. Security and Privacy Considerations says: "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." I'm struggling to understand how this is the case; doesn't CanMakePaymentEvent allow this? And is it clear to the user what information is being shared with whom?
• Likewise, the meaning of "Similarly, user agents should not share payment request information with any payment handler until the user has selected that payment handler." isn't clear to me in the presence of CanMakePaymentEvent.
• 8.4 Payment App Authenticity sounds good, but it's not clear if this specification describes a mechanism that allows it to be enforced. More detail would be helpful.
• 8.5 Supported Origin should link to the normative text that it refers to.
• 8.6 Data Validation should probably be expanded a good bit; shouldn't payees also validate against data from a connection they have to the payment processor in many cases?

[dbaron]

One other concern about malicious payment handlers that just occurred to me is that it seems like CanMakePaymentEvents have data about the payment total, which means that a payment handler could choose to only accept refunds and not debits. This makes me a little bit more worried about malicious payment handlers.

[triblondon]

Is there any potential issue with users acquiring tonnes of payment handlers without realising it, and those payment handlers existing purely to bring spam content to the user's attention? Like wireless APs that exist purely to broadcast adverts in SSIDs ("evil.xyz for good times!"), could there be a reason to install a payment hander for reasons other than the designed purpose?

[triblondon]

The TAG has previously encouraged the merging of manifest formats - having manifests for multiple parts of the web platform with overlapping goals transfers cognitive load onto web developers, and creates debuggability issues.

Where possible, we strongly recommend using or extending web app manifest. It does seem like the payments ecosystem work does require some manifest data that is not origin-scoped, but we want to emphasise the cost to developers of manifestitis and encourage their reduction and removal.

[dbaron]

One other note about manifests (maybe repeating above) is that ImageObject is similar to web app manifest's ImageResource, but it:

• doesn't have the two last properties
• has a differing type for type (DOMString vs. USVString)

[torgo]

Bumped to 5-29.

[dbaron]

I went through the responses above, and have a few comments on them:

• I'd still be interested in seeing a reaction to the points in the first paragraph of "Extensibility, permissions, and UI" in Payment Handler #231 (comment) -- in particular, whether the API offers enough information to present sufficient information to the user at the time of installing the payment handler, if user agents believe they should be more restrictive at install time?
• the biggest concern behind my question about "running the necessary level of detail through the API" was more about whether the issue of presenting content from the handler's UI inside of browser chrome was a workaround for deficiencies in the API. I see that you've said that you think it's not feasible to avoid this -- but what happens if other browsers aren't comfortable with putting this content inside of browser chrome? It seems like we're then stuck with very little information coming through the API.
• my concern about new mechanisms of communication was about whether this added capabilities to communicate across domains (e.g., through a service worker, i.e., allowing communication across domains when the user was interacting with only one of the sites) that didn't exist before. I think @slightlyoff convinced me during the last (?) TAG face-to-face that this wasn't an issue, but I don't recall the details. I think my concern was that this might be adding an ability to communicate data across origins without network traffic, which could possibly be used to do things like track users across domains without network traffic.
• I'm still concerned about some of the items in my "Other" section in Payment Handler #231 (comment) , especially the first item about specifying how these various Web Payment specifications relate to each other, e.g., the relationship between payment method identifiers and manifests. Many of the other items there are details, but I'm curious if you've looked into them.
• I followed up in ImageObjects can now reference ImageResource w3c/payment-handler#238; sorry for missing that earlier.

[slightlyoff]

I think we did agree that this isn't a new communication channel because <iframe>

[rsolomakhin]

@dbaron wrote:

I'd still be interested in seeing a reaction to the points in the first paragraph of "Extensibility, permissions, and UI" in #231 (comment) -- in particular, whether the API offers enough information to present sufficient information to the user at the time of installing the payment handler, if user agents believe they should be more restrictive at install time?

The API makes a service worker into a payment handler when the service worker registers its first instrument. This instrument can contain payment method identifier, instrument name, and instrument icon. All these could be presented to the user in a prompt. The payment method identifier in particular can be used to explain the types of payments that could be handled, e.g., "basic-card" or "tokenized-card".

Because Chrome does not present individual payment handler instruments in its UI, Chrome instead downloads the web app manifest of the current page at the time of payment handler installation and saves the icon and name information from there. These also can be presented to the user in a prompt.

@dbaron wrote:

the biggest concern behind my question about "running the necessary level of detail through the API" was more about whether the issue of presenting content from the handler's UI inside of browser chrome was a workaround for deficiencies in the API. I see that you've said that you think it's not feasible to avoid this -- but what happens if other browsers aren't comfortable with putting this content inside of browser chrome? It seems like we're then stuck with very little information coming through the API.

It would be difficult to define an API that can accomplish everything that a payment handler might need. For example, a payment handler may ask the user to re-enter their password, enter a captcha, or update their billing address. Therefore, we believe that allowing the payment handler to display an HTML page is the best option.

Another school of thought is that the API must be at least as useful as the existing solutions of iframes and popups. If we restrict the payment handlers too much, API adoption would suffer.

In addition, although Chrome currently displays payment handler's UI in a dialog, it is also possible to use a popup or a new tab to display the payment handler UI in a more canonical way.

@dbaron wrote:

I'm still concerned about some of the items in my "Other" section in #231 (comment) , especially the first item about specifying how these various Web Payment specifications relate to each other, e.g., the relationship between payment method identifiers and manifests. Many of the other items there are details, but I'm curious if you've looked into them.

I have filed issues w3c/payment-method-id#52, w3c/payment-handler#308, w3c/payment-handler#309, and w3c/payment-handler#310 to address these.

[dbaron]

Thanks for your request for review here, and we look forward to seeing developments in the issues broken out here, and seeing future reviews for future work as well. But we don't feel we need to cycle back to this issue again.