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

Before I dig in and do a full review, I'm really grateful this spec has
extensive examples. It means I, as a reader, know how to read the spec and
get an impression of the user flow.

Not only is this useful for someone who isn't an insider to the working
group, it provides proof that the developer experience has been considered.
This is probably the case with the current spec, but it isn't evident from
a glance.

On Mon, 23 Jan 2017 at 09:24 Marcos Caceres <mcaceres@mozilla.com> wrote:

> ## tl;dr - a New Approach
> Top posting because I think we need a reformulation of the Payments Apps
> API.
> I propose a new API shape here:
>
> https://marcoscaceres.github.io/payment-request-handler/
>
> * It addresses all the same use cases/requirements.
> * It integrates with PaymentRequest - allowing implementation of
> `PaymentResponse` in Service Workers.
> * It solves the canHandle() issue.
> * It solves the identity problem (it's just origin).
> * It solves the "manifest" problem (use it if it's there!) - and doesn't
> require trashing everything any time there is an update.
> * it provides a secure way to open a payment flow window.
> * 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.
>
> The above is just the API shape (no algorithms yet), but it shows how it
> is expected to work with the code examples.
>
> ## 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 is impossible to implement, it's obsessed with the idea of
> "manifests", 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.
>
> ## 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.
>
> 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.
>
> ## 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.
>
> ## R3. Payment Handling
> The existing API fails to capture all the possible events sent from a
> PaymentRequest object. 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.
>
> 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:
>
>  * .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.
>
> ## 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.
>
> 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.
>
> ===
>
> 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.
>
> Kind regards,
> Marcos
>
>
>
>
>