RE: Review of Payment Apps Proposal

Adrian,

I'd like to echo that thanks Manu provided on this.

I too support the bringing of this specification into the WG.

The comments I have in addition to Manu's are;

Section 1. "Payment Apps support one or more payment methods for processing payments initiated via the Payment Request API." I think this is somewhat misleading as the PaymentApp may in fact no process  the payment at all, the BasicCardPayment specification performs no payment processing, it just provides data. Even an authorisation is not considered 'processing'. On this subject (though clearly not for this section of the document) I do believe that it would be useful to pass the state of the payment in a standard field back to the user-agent as we have discussed before as an enumeration (e.g. authorised, captured, etc.). 

6.2.1.3 Resolving the PaymentResponse Promise. I think we need to be explicit about how error conditions should be handled? For example how does the app represent factors such as user cancellation, user failed to authenticate, unexpected error etc. to the payment mediator?

6.3.2 Platform-specific Payment Apps, this section states undefined, do you expect the group to expand on this or do you intend it to remain this way through to publication?

Lastly, out of band communications have not been mentioned, I think they should be for clarity. I believe you raised an issue on if some sort of standardisation of this should be done and I suggest this is referenced here.

Regards,
Matt

-----Original Message-----
From: Manu Sporny [mailto:msporny@digitalbazaar.com] 
Sent: 21 April 2016 04:14
To: Web Payments Working Group
Subject: Review of Payment Apps Proposal

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/




---
This email has been checked for viruses by Avast antivirus software.
https://www.avast.com/antivirus

Received on Friday, 6 May 2016 13:48:15 UTC