Two high-level comments on "Payment Apps" draft

Hi Adrian,

Thanks for starting work on the Payment Apps spec [1]. I have two
high-level comments. I wanted to discuss a bit by email before
suggesting concrete text changes.

I did not study the technical portions of the spec. My main observation is that
I'd like a clearer explanation of the Payment App lifecycle
and payment flow up front, before diving into API details.

Here are the topics that I think we should cover, both
in an overview, and then in more detail in the main
part of the specification:

PAYMENT APP LIFECYCLE:

 * USER REGISTRATION OF PAYMENT APP WITH A MEDIATOR
 * PAYMENT COMMUNICATION OF UPDATES TO MEDIATOR
   (e.g., when Payment App is updated by the user,
    or when the user registers payment instrument
    information after initial registration)
 * USER UNREGISTRATION OF PAYMENT APP WITH A MEDIATOR

PAYMENT FLOW:

 * USER AGENT COMMUNICATION OF PAYMENT REQUEST TO MEDIATOR
   (Matt Saxon has suggested we distinguish these two parties,
    at least formally. See also the use of “meditator" in the  architecture [2], which is
    why I emphasize it here.)

 * MEDIATOR COMPUTATION OF RELEVANT USER PAYMENT METHODS

   Mediator computation of the intersection between merchant-accepted
   and user-enabled (to use your term :) payment methods. This
   content includes the "supported" v. "enabled" distinction.

 * MEDIATOR SUPPORT FOR USER SELECTION OF PAYMENT APP

   Mediator interaction with the user for payment app selection.
   Note that this will not be a long section, but may address topics
   like management of merchant-specified payment method order.

 * MEDIATOR INVOCATION OF PAYMENT APP

   This includes calling the Payment App and providing the payment
   request data as input. The spec will need to address Web v.
   native scenarios.

 * PAYMENT APP RESPONSE TO MEDIATOR

 * MEDIATOR COMMUNICATION OF PAYMENT RESPONSE TO USER AGENT

I think this aligns strongly with your draft. I wanted to call out the actors
clearly as a backdrop to the conformance comments below.

==============
ON CONFORMANCE

It also seems to me that there needs to be greater clarity about
conformance. For example, the above suggests that:

 * Conforming mediators will have to do some things:
   - register payment app data.
   - compute the payment method identifier intersection
   - respect whatever small number of user experience requirements
     we have (ordering of payment methods, minimal requirements
     for user selection of app whatever those might be, etc.)
   - instructions for invoking the payment app and providing it data
   - handling of response data

 * Conforming payment apps will have to do some things:
   - format registration data according to the specification
   - handle payment request and response data however we require.

 * If we decide to distinguish (formally) user agents and mediators,
   there will also be requirements for user agents.

While I'm talking about conformance, I think there's a bug in section
4.1. You talk about Payment App handling "Payment Transaction Message
Specifications." Conformance by a Payment App to such a spec should be
defined in that specification, not in the Payment App spec. In other
words, "if you claim conformance to Basic Card, you had better satisfy
that spec's conformance requirements." Thus, I think the fourth paragraph
of 4.1 needs to be revisited because it's not the job of Payment
App to define conformance to those other specs.

Meanwhile, could we call those other specs "Payment Method Specs"
rather than "Payment Transaction Message Specs"? Those specs
will include information about payment method identifiers as well.

[1] https://w3c.github.io/webpayments/proposals/paymentapps/payment-apps.html
[2] https://cdn.rawgit.com/w3c/browser-payment-api/0d1d5d7ff0f1bb7b37970994f1eb719101aaccbc/fpwd/architecture.html#payment-mediators

--
Ian Jacobs <ij@w3.org>      http://www.w3.org/People/Jacobs
Tel:                       +1 718 260 9447