Re: Rethinking Apps Payments API, Re: Payment App API: updated flow description

Hi Marcos,

This is an interesting development, although it's not clear to me what it
is trying to solve with the current API or why a complete re-write is
better than working through the issues that remain with the task force that
has been working on them for over a year.

* It addresses all the same use cases/requirements.
>

So no different from the current spec?


> * It integrates with PaymentRequest - allowing implementation of
> `PaymentResponse` in Service Workers.
>

The current API design is intentional. The WG decided that passing the
entire Payment Request to the payment app was a bad idea so this is a
regression.

https://github.com/w3c/webpayments-payment-apps-api/issues/2


> * It solves the canHandle() issue.
>

It's not clear what you mean by the "canHandle()" issue. It would be
usefgul if you provided a link to some issue(s) so we can understand what
you're solving.

If you are referring to Issue #92 then I think @ianjacobs has done a pretty
good job of summarizing the goals of canHandle() here and I'm not sure then
what the issue is: https://github.com/w3c/webpayments-payment-apps-api/
issues/92#issuecomment-274097944


> * It solves the identity problem (it's just origin).
>

Again, it's not clear what you mean by "identity problem". Also this is a
rather naive solution because Service Workers are not identified by "just
origin" they are identified by their scope URL. So are you proposing that
Payment Apps are special kind of Service Worker for which only 1 can be
registered per origin?


> * It solves the "manifest" problem (use it if it's there!) - and doesn't
> require trashing everything any time there is an update.
>

Again, not sure what you mean by "manifest problem". Manifests, in the
context of payment apps, serve a simple purpose (similar to the purpose of
app manifest) which is to provide icons, labels and descriptions for an app
so that a browser can present a user with UI for selecting an app from a
list.

Unfortunately the spec has used the term "manifest" despite the
implementation being inconsitent with "app manifest" (the current proposal
is to pass the "manifest" as a Javascript object into the registration flow
of the Service Worker as opposed to storing it as a JSON file) so it has
caused some confusion.

It's important to note however that the manifest is only required to
support the recommended apps functionality so if we drop recommended apps,
which is gaining support, then there is no "manifest problem" because there
is no manifest.



> * it provides a secure way to open a payment flow window.
>

It's not clear to me how the proposal is different from what is being
discussed in the Payment Apps TF (
https://github.com/w3c/webpayments-payment-apps-api/issues/73). The current
spec will provide the same functionality but the group is taking the time
to figure out the best way to do this while being cognizant of the
different form factors and UX that this involves.


> * it doesn't magically fill in stuff (e.g., shipping address) - giving the
> payment handler more control over the response, and providing the ability
> to create much richer payment handling web applications.
>

Again, not passing the "information request" aspects of a Payment Request
to the Payment App was a decision taken by the group so the current design
is intentional.

Only the mediator/browser interacts with the web page to provide user
details. Payment Apps are exclusively for handling the payment.

https://github.com/w3c/webpayments-payment-apps-api/issues/13


>
> The above is just the API shape (no algorithms yet), but it shows how it
> is expected to work with the code examples.
>

Unfortunately the devil is in the details and as I have said above you are
regressing on a number of design decisions that the WG has already taken so
if your goal is to simply tweak the API shape I'd suggest doing so by
suggesting changes to the existing spec.


>
> ## The long version
> Firstly, I must acknowledge that the current API (and surrounding
> discussions) have done a great job at formulating the use cases and
> requirements for this API. Thus it serves as an important foundation to
> build on.
>
> However, the current Payment API does not meet the use cases (listed
> below),


It would be helpful if you could explain why you think this is the case


> it is impossible to implement,


Again, some detail on why you think this is the case because we already
have working implementations so "impossible" seems like a strong word here.


> it's obsessed with the idea of "manifests",


I suspect you have hopped onto the back of a very recent discussion which
is attempting to solve for a requirement that many of the merchants in the
group feel strongly about; recommended apps.

There is a desire to allow merchants to recommend apps to their customers
as a way to bootstrap the ecosystem. To do this it is necessary for the
browser to present the user with a list of one or more apps that are not
yet installed therefor the browser must source the necessary meta-data (an
icon, label etc) about the app from somewhere. One of the proposals is a
manifest.


> and has become bogged down in issues that are clearly outside it's scope:
> like, trying to change the web security model, issues of application
> identity, etc).


> These are tremendously important problems, but they are outside the scope
> of this work. Those are issues that we need to address universally in the
> web platform, but they are not issues that this working group can solve in
> isolation.
>

Can you point at some issues where this is happening. On the contrary I
think the group is at pains to try and adhere to the existing models and
re-use what is available as much as possible.


>
> ## Let's start with use cases and requirements
>
> The fundamental *use cases* are:
>
> 1. Register an web app, with user consent, to handle requests for payment
> of particular types (e.g., credit cards, a proprietary payment method).
> 2. Allow the end-user to manage payment methods (adding, deleting,
> modifying, etc.) - and for these methods to be available as payment options
> upon request for payment. This includes providing both visual and
> accessible representations of those payment methods (i.e., icons and text).
> 3. Allow merchants to query if those payment methods are available at
> point of sale.
>
> The *requirements** are thus:
>
> R1. Registration: Provide a means for a web application to get user
> consent to act as a payment handler (a "powerful feature", amongst other
> powerful features).
>
> R2. Payment Method Management: Where there are multiple payment methods,
> provide a means to allow the end-user to manage payment methods.
>
> R3. Payment Handling: handle "request" for payment, and facilitate
> communication between a `PaymentRequest`, the end-user (through a payment
> UI), and a `PaymentResponse` on a third party site.
>
> R4. UI to make payment: provide a means for a web application to spawn a
> window-like context in which to perform a payment method.
>
> R5. Can handle: Provide a means to check if a payment handler can handle a
> payment.
>
> Now we can look at how the current API is deficient in addressing these
> use cases - and how the new API can address the requirements.
>
> ## R1 - Registration
> The current API conflates web app manifest and payment manifest, etc. In
> relation to other powerful features afforded by the web platforms there is
> nothing special about the payments response API that requires it to have a
> manifest.
>

I think you are getting a bit obsessed with the manifest topic.

Nobody is proposing that the API have a manifest but the current spec
proposes that when a payment app is registered it provides some information
about itself to the PaymentAppManager (icon, label etc) which are often
stored in an app manifest.

As I have said to you numerous times the goals is to try and re-use some of
what is already defined for the Web platform (eg: the data structures in
app manifest for describing icons) so that this WG doesn't try to reinvent
everything.

If you read issue #48 you'll see that there is not a final decision on how
a payment app (during it's registration flow) will provide the icons, label
and other meta data it must provide to the browser. The current proposal is
a Javascript object passed to the registration function. This is called a
manifest which is clearly creating some confusion, although it must be said
"app manifest" didn't invent that word, it's a pretty well understood term
for application meta-data so using it here is appropriate.


> How Payment Requests API solves this:
> Having a web manifest is not a requirement for "payment handlers".
> However, a web application can include a web manifest.
>
> To get permission to act as a payment handler, the new API allows the
> developer to ask for permission via the a call to:
> paymentAppManager.requestPermission()
>
> This allows the browser to intervene and negotiate with the user if the
> application can act as a payment manger.
>

Hooking handlePayment into the permissions framework is a good idea but not
a new one. The existing registration algorithm already proposes that the
user be asked to grant permission to the app.

We could certainly use some help to ensure this language is improved to
make it clear that this is intended to be part of the existing browser
permissions framework.


>
> ## R2 - Payment Method Management
>
> The current API only has two methods for handling payment methods - and
> those are conflated with "manifests":
>
>  * setManifest()
>  * getManifest()
>
> This makes it impossible to manage payment methods without continuously
> trashing the existing payment methods and "the manifest". This makes it
> difficult to get at current payment methods, and modify and work with them
> individually.


> How the new API solves this:
> The new API introduces a `PaymentMethodMap`, which allows for asynchronous
> atomic management of payment methods (add, delete, iterate, etc). Exposed
> on window and workers.
>

What this ignores is that each payment method is a new permission that the
user should consent to granting the app.

If I have given an app permission to make a certain type of payment then I
don't expect it to be able to make other kinds of payments because it
silently added supported payment methods in the background.

Again, while you may not think the API is very developer friendly it's
design is intentional. It may also not be perfect but there are some design
considerations that you are ignoring.


> ## R3. Payment Handling
> The existing API fails to capture all the possible events sent from a
> PaymentRequest object.


As discussed above this is by design. Those events are only supposed to be
for the sake of the website and browser.


> It then goes on to introduce new primitives instead of just using
> PaymentResponse. As such it fails to integrate fully with `PaymentRequest`,
> and fails to allow bi-directional communication between PaymentRequest and
> PaymentResponse.
>

As discussed above this is by design.

At the time of designing Payment Request we made the decision we wanted
payment apps to be implementable in any form (web-based, native etc) and
for the interface between the website and browser to be the same.

This is a compromise but was made intentionally. The result is that there
is a bidirectional interaction between the website and browser initially
and then a single request passed beyond the browser and single response
that comes back.

It may be that we need to reconsider this approach but I'd want to hear
from implementors that are planning to support native payment apps (like
Android) if this is something they'd support. There are issues with
background processing on low spec devices to consider here, it's not all
simple.


>
> The new API solves this by giving PaymentResponse a constructor - allowing
> ev.respondWith() to actually respond with a PaymentResponse and by allowing
> the "onpaymentrequest" event to catch the various events resulting from
> calls to PaymentResponse - for instance:
>

As discussed this is also by design.

The group made the decision that the payment app should not be passed the
complete payment request but rather a modified trimmed down version with
only the data relevant to it.


>
>  * .onabort() can now be handled.
>  * Response.updateShippingAddress() - can notify the PaymentRequest with
> a new address, and await a response from the PaymentRequest to check if
> it's ok.
>  * Response.updateShippingOption() - as above, but with a new shipping
> option id.
>
>
Sourcing shipping and email data from the app has never been a goal of this
WG.


> ## R4. UI to make payment
> The current API is hand-wavy about using clients.openWindow() in a service
> worker to perform the payment flow. This solution is inadequate (or simply
> not any better) when compared to what browser do today.
>

I wouldn't call it hand-wavy, I'd say it is still being discussed. It's
likely the final solution will be just as you describe but we're getting
there by considering all the implications, form factors etc


>
> The new API introduces a the ability to open a payment-specific payment
> flow window via `PaymentRequestEvent.openClientWindow()`. This allows the
> browser to bring up an appropriate payment window for the purpose of
> negotiating a request for payment.
>
> ## R5. Can handle payment
> The current API tries to define `canHandle` the the manifest - by defining
> a new type of function that appears to be transferrable across threads.
> That is: if the payment app is closed, the function is somehow magically
> supposed to still be active (!). This is impossible to implement, because
> functions are dynamic and associated with their global environment (and
> contain closures). Hence, it's not something that can be implemented - not
> without changing how JavaScript works, which is just not going to happen.
>
> The new API addresses this by adding a "canhandlepayment" event on the
> service worker instead. Registered handlers can then be woken to check if
> the payment method is supported - by performing whatever checks are
> necessary.
>

I am no expert on the internals of browsers or their threading models and
how they allocate processing to JS or sandbox and GC these processes.

This sounds like a good suggested change, perhaps you could propose it
against the existing API?


> ===
>
> Obviously, people will have a lot of questions. Let's work through those!
>
> There is lots of stuff we can take directly from the existing API too - we
> should totally do that where it makes sense.
>

I think you have designed the new API lacking a lot of context and
background discussion and design decisions. There are some good ideas but I
don't think starting again is a a good idea at all.

If you are able to join the weekly Payment App TF calls it would be great
to look at some of the ideas in here as possible additions or edits to the
existing spec.

If the group feels we should re-open some previous discussion like allowing
a bi-directional channel between apps and the calling website or allowing
apps to participate in providing the non-payment related (shipping, email
etc) data then I'd like to hear proposals to do that and why before we jump
straight to a whole new technical proposal.


> Kind regards,
> Marcos
>
>
>
>
>