Re: Review of Payment Apps Proposal

Hi Manu,

Thanks for the review, I have not been through it yet in detail but will do
so.

Based on the discussions around re-organizing the group's documents (
https://github.com/w3c/browser-payment-api/issues/138) I took a first stab
at a new architecture document which I have put here:

https://w3c.github.io/webpayments/proposals/architecture/

If we do follow this route I'd recommend that what I have put into the
payment apps proposal is split three ways:


   1. Some elements of it will be incorporated into this new architecture
   document. (Note that some of the content from the payment apps proposal has
   already been incorporated.
   2. The user agent specific elements regarding registration and passing
   payment messages between the user agent and apps (and WebIDL interfaces for
   this) should be incorporated into the browser API spec a these are browser
   specific.
   3. The manifest specific elements should be submitted for inclusion into
   the manifest spec (I have already started engaging the editors on this).

There is a concern from the browser API spec editors that we should keep
registration in a separate spec so that the payment and registration specs
can evolve independently. I think there is a case to be made that these
should be in the same spec as they relate to the same component (the
browser) and the sections of the spec that relate to each function can
still evolve independently.

Thanks again for the thorough review, I will incorporate your comments into
the work I am doing on the architecture doc and into some PRs on the
browser API spec.

Adrian

On 21 April 2016 at 05:14, Manu Sporny <msporny@digitalbazaar.com> wrote:

> Hey AdrianHB,
>
> Thank you for putting together the Payment Apps proposal. This is a
> complete review of the proposal with feedback and suggestions where
> appropriate. I'm a +1 for adopting this as a work item in the WG.
>
> Clearly, I don't expect a response to the comments below before we
> officially pull the spec into the group as a work item since we'll be
> discussing that decision 13 hours from now.
>
> Front Matter
> ============
>
> > Payment Apps
>
> I think pubrules requires that you include a version number in the
> title. Also note that you can have a subtitle, which I recommend you
> provide. For example, "Web applications for executing web payments"...
> or something like that.
>
> > Adrian Hope-Bailie, Ripple
>
> Please create links to the appropriate sites for Ripple and your name,
> if applicable.
>
> > registered with a user agent using a manifest file
>
> Strike "using a manifest file" - you don't need to provide
> implementation details in the abstract.
>
> > and and how the user agent interfaces
>
> Strike one of those "and"s
>
> > maintains a list of all bug reports that the group has not yet
> > addressed.
>
> The link to https://github.com/w3c/browser-payment-api/issues is wrong.
>
> > No decision has been taken
>
> Use no decision has been "made", instead?
>
> > The Payment Request API [PAYMENTREQUESTAPI] defines
>
> Normative dependency on Payment Request API is wrong here. It should be
> the other way around. Payment Request API should have a normative
> dependency on Payment Apps.
>
> > registered by the payer with the user agent to
>
> Shouldn't this be "registered by the payer with the payment mediator/agent"
>
> > initiated via the Payment Request API.
>
> What about the HTTP API?
>
> > to the calling Website.
>
> Use more specific terminology? "payee website"? "payee"? Why is
> "Website" capitalized?
>
> > the payment request may be passed to the payment app.
>
> You're mis-using the "MAY" language here. Use a different word. MAY
> means something specific and I don't think you mean that version of
> "MAY" here.
>
> > How a payment response may then returned by the app
>
> Same "MAY" problem here
>
> > How a payment response may then returned by the app to the user
> > agent?
>
> We need to be clear about the flow. Is the response returned to the user
> agent? Or the payee website? Or the payment mediator/agent? This
> language needs to stay consistent across the specs.
>
> > Payment Request system described in the Payment Request Architecture
> >  [PAYMENTARCH] document.
>
> We should rename this to "Web Payments Architecture"... which may
> consist of more than just payment requests and responses. What about
> subscription requests? Preauthorization requests?
>
> > Allow users to register payment apps with their user agent
>
> I assume this "register with user agent" and "register with payment
> mediator/agent" will get resolved in time. We just need to pick some
> language and go with that. I hope that we end up with "register with
> payment agent".
>
> 1.1 Goals
> =========
>
> You don't mention anything about payment responses in the goals section.
> We should make one of the goals:
>
> Standardize a platform-independant mechanism for a payment app to return
> a payment response to the payee website via the user agent.
>
> 2. Conformance
> ==============
>
> > Also, we should look at the conformance criteria for user agents as
> > defined in [APPMANIFEST].
>
> Why should we look at that section? Because it's a good model to follow?
> Or because there are issues with it?
>
> > in this specification, user agent means a Web browser or other
> > interactive user agent as defined in [HTML5].
>
> Does this mean a non-interactive HTTP client doesn't need to meet the
> conformance criteria?
>
> > A conforming user agent must also be a conforming implementation of
> > the IDL fragments of this specification, as described in the “Web
> > IDL” specification. [WEBIDL]
>
> This conformance requirement makes no sense for an HTTP client as those
> clients typically do not expose any sort of programming environment and
> thus the WebIDL hooks could never be tested for conformance.
> Additionally, those WebIDL interfaces shouldn't be a requirement for
> HTTP clients. Instead, we should just say that HTTP clients need to be
> able to register and update their payment apps (and provide algorithms
> for doing so).
>
> 3. Dependencies
> ===============
>
> > Payment Request API
>
> I don't understand why the Payment Request API is a dependency for
> Payment Apps. HTTP-only Payment Apps are not going to expose the Payment
> Request API at all.
>
> > Web App Manifest
>
> I have very serious reservations about requiring a full Web App Manifest
> for something as lightweight as a Payment App. Simple HTTP-only clients
> will have a very hard time meeting this requirement.
>
> > HTML5 ECMA-262 DOM4 WebIDL Secure Contexts Fetch
>
> Again, why does a simple HTTP-only client need to pull in all these
> requirements to process a simple payment request and response?
>
> 4. Payment Apps
> ===============
>
> > Payment Apps are a specialized form of installable application as
> > defined in [APPMANIFEST]. They could take the form of Web apps,
> > interface-less Web services, platform-specific native applications
> > or even user agent components or extensions.
>
> Again, not sure we need the APPMANIFEST stuff to achieve
> "installability" of payment apps. Why can't we just have a simple JSON
> description of a Payment App that describes icons, HTTP endpoints, etc.
> Why do we need all the extra functionality of APPMANIFEST? Have we
> talked w/ Marcos Caceres, Kenneth Rohde Christiansen, Mounir Lamouri, or
> Anssi Kostiainen about this use of APPMANIFEST? Do they think it's a
> good idea to put those requirements on an HTTP API?
>
> 4.1 Supported vs Enabled Payment Methods
> ========================================
>
> I really like this section and is the sort of language I'd expect to be
> in a payment app spec. I think stuff like this is what should comprise
> the Payment App spec (along w/ general algorithms).
>
> > defined in the Payment Transaction Message Specification for that
> > payment method and should be able to return an appropriate response.
>
> I tried to look up "Payment Transaction Message Specification" and
> didn't find anything. Is that spec proposal forthcoming?
>
> 5. Registering a Payment App
> ============================
>
> > The process of Payment App registration follows the process defined
> > for installing an application via a manifest, as described in
> > [APPMANIFEST]
>
> -0.5 to this, APPMANIFEST is too complicated to pull in, especially in
> the case of a simple client that only needs to support the HTTP API.
>
> > This specifcation also defines an extra mechanism for triggering the
> > installation process via an API call as described in
> > registerPaymentApp.
>
> I strongly suggest that we take this approach instead of the APPMANIFEST
> route. It's simpler. It is also a mechanism that we control the REC
> track timeline for, which will become very important if we want to get
> registration out to REC on a reasonable timeframe AND will reduce the
> amount of stuff that needs to be implemented in a browser before the
> browser can implement the browser API.
>
> 5.1 Manifest and its members
> ============================
>
> > Unfortunately the [APPMANIFEST] specification does not have a way of
> > installing a manifest via a browser API so there is no WebIDL object
> > definition of the basic manifest. It is declared here but a PR will
> > be made against the [APPMANIFEST] specification to include it there
> > following which this section could be removed.
>
> I believe that adding this to APPMANIFEST would ultimately be good for
> the Web. That said, I don't want us to take on that very steep uphill
> climb (APPMANIFEST API) while we're engaged in our own very steep uphill
> climb (payments APIs).
>
> I assert that all we need is something that looks like the Manifest
> object to be passed to the registerPaymentApp() call. If we do that, we
> avoid pulling in APPMANIFEST entirely.
>
> 5.2 registerPaymentApp()
> ========================
>
> Huge +1 to the shape of this API.
>
> That said, I don't think the Payment Apps spec should have any WebIDL in
> it - rather, the WebIDL should be moved to the Browser API spec.
>
> > Perhaps a payment request should be instantiated via a factory method
> > like navigator.payments.createPaymentRequest?
>
> Yes, please.
>
> > Promise<PaymentApp> registerPaymentApp(DOMString manifestURL,
> > boolean useCredentials);
>
> I'd rather "manifestURL" be changed to "manifest" and the argument be a
> Manifest-like object.
>
> > update a payment app installation. It executes the the same process
>
> This is tricky, how do we update if we get rid of the APPMANIFEST
> dependency. We could allow the Manifest object to have an "update" URL
> that contains access credentials so that it may be queried/updated in a
> background process from time to time. Clearly, there are security
> implications there.
>
> > which is a flag to indicate if the [FETCH] request should include the
> > credentials of the current user.
>
> So payment agents that implement the HTTP API are required to also
> implement Fetch? I don't think I agree with pulling in that heavyweight
> requirement, especially since FETCH is very browser specific.
>
> As an alternative, we could require an authentication mechanism that can
> be executed by the agent on behalf of the payer without needing user
> interaction after the first access. For example, cached Digest
> authentication? HTTP Signatures? OAuth?
>
> 5.2.1 PaymentApp and its members
> ================================
>
> > registerPaymentApp(manifestUrl, true).then(
>
> boolean trap - don't do it:
>
> http://ariya.ofilabs.com/2011/08/hall-of-api-shame-boolean-trap.html
>
> 6. Processing Payment Requests
> ==============================
>
> > This specification explicitly ctare for three categories of payment
> > app
>
> "ctare"? Did you mean "caters"?
>
> What are the three categories?
>
> > An HTML response that must rendered by the user agent in the
> > application context defined by the payment app's manifest.
>
> This makes it seem like there is only one HTML page that is displayed...
> could the HTML page displayed contain redirects to other code that may
> eventually return a payment response? If so, how does this payment
> response get back to the payee website code?
>
> 6.2 Submitting the PaymentRequest to the Payment App
> ====================================================
>
> > Let request be a new [FETCH] request, whose members are set to the
> > following values:
>
> Again, I have deep concerns about pulling in the complexity of FETCH
> into payment agents that only implement the HTTP API.
>
> > Accept        text/html;application/json
>
> This Accept line says that the browser doesn't have a preference between
> text/HTML (interactive) and application/json (non-interactive)?
> Shouldn't we prefer automated responses if available?
>
> > How do we signal that this JSON is a PaymentResponse?
>
> You could include application/ld+json as preferred over
> application/json. In either response case, you could specify a "type"
> key with "PaymentResponse" as the value.
>
> 6.3.1.1.1 Accepting the PaymentResponse
> =======================================
>
> > Promise<boolean> submitPaymentResponse(PaymentResponse response);
>
> What does the boolean value mean?
>
> > It does this by calling submitPaymentResponse.
>
> Again, +1 to this API shape... but it belongs elsewhere (like in the
> Browser API spec). The HTTP API spec has no need for these WebIDL
> interfaces.
>
> 6.3.1.2 Autonomous Payment App services with no user interface
> ==============================================================
>
> > that requires no user interface hen the response
>
> Misplaced chicken. "hen" -> "then"
>
> 6.3.2 Platform-specific Payment Apps
> ====================================
>
> > In this case the response data will be platform specific.
>
> Why? Shouldn't the payee website expect a payment response as a result?
> I'd expect the payment request and the payment response to be the same
> and use promises to resolve the payment response. All the piping is
> different, but we may want to push the conformance criteria a bit more
> and say that a best effort must be made to hand the payment request to
> the native app in the same format as what is expected in a web-based
> payment app. The same goes for payment responses - a payment response is
> expected that matches the same criteria that a web-based payment app is
> required to generate.
>
> So, to summarize:
>
> * The WG should adopt and further refine this proposal
> * The heavy requirements on browser tech for HTTP API payment agents
>   is problematic
> * The WebIDL feels like it belongs elsewhere (in the browser API spec)
> * The core algorithms should be generalized more with less assumptions
>   about them being executed in a full blown browser environment (which
>   is not the case for the HTTP API payment agents).
>
> Again, thanks for putting in all the hard work into this spec, AdrianHB.
> Much appreciated. :)
>
> -- manu
>
> --
> Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny)
> Founder/CEO - Digital Bazaar, Inc.
> blog: Web Payments: The Architect, the Sage, and the Moral Voice
> https://manu.sporny.org/2015/payments-collaboration/
>
>
>