Comments on Web Payments HTTP API 1.0

Manu, Dave,

Thank you for proposing:

  Web Payments HTTP API 1.0
  https://w3c.github.io/webpayments/proposals/web-payments-http-api/
  9 April 2016

(There is a problem when loading the spec; I had to hit "escape" to get the document.)

Here are some initial comments for the discussion about
the Web Payments Working Group taking this on. I expect that
some of my comments below reflect not yet completed work
to translate the CG spec into a WG deliverable consistent
with current WG usage.

Ian

====================
Comments on the text


2. Payment Flow Overview

 * "The payee provides a location". I prefer not to use location.
   What about "identifies a service" ?

 * "...and sends the request and the selected app on to the appropriate
   payment service provider for processing". A payment app
   is defined to be software. I don't know what it means to forward
   the software to a PSP.

 * "4) A payment app is selected by the payment agent or the payer. The
      process MAY consist of one or more of the following steps:"

   It seems to me that either this section should be "normative" or
   it should be moved elsewhere if only suggested behavior.

 * "6.1) The payment agent". That term is not defined.

 * Looking at the examples, "acceptedMethod" includes information
   about payment method identifiers and the offer (amount/currency).
   However 7.1 seems to suggest that there is additional information
   about a paymentRequestService possible.

 * In this section, 5, 6, and 7 speak about three forms of
   third party processing. For a given payment method, how does
   the relevant software know which one is applicable?

 * "Once the entity in control of the payment flow finalizes the
   payment acknowledgement, even if the message is to acknowledge that
   the payment failed, the payment acknowledgement is generated and
   the payer's payment agent is notified via an HTTP 200 success
   code."

   It is not clear to me that HTTP 200 should be used in the
   case of an unsuccessful transaction.

3.1 Payment app Registration.

   * I would prefer that we work on payment app registration
   separately, and suggest that it not be defined in this
   spec. Instead, let's focus our efforts on one registration spec (at
   least for now).

3.2 Processing a Payment Request

   * The section title seems broad. How about "Initiating a Payment Request"?

   * "2. The payee server notifies the payer that a payment is
      required along with a payment request."

     I may be wrong, but this seems to conflict with the flow
     described in section 2. Section 2 says: "The payee's web page
     requests payment by responding with a 402 Payment Required
     response code and a URL encoded in the Location header to fetch
     the request from. " In other words, there's an extra "fetch"
     required in section 2 that is not required in 3.2.

   * It seems there's a missing step where the user agent
     invokes the processor. I say "missing" because the
     next section (3.3) is about acknowledgment but 3.2 does not
     (yet) speak about processing.

3.3 Processing a Payment Acknowledgement

   * "which is a [JSON-LD] object". This seems to be the only
      mention of JSON-LD outside of 3.4, so I expect it was
      intended to be plain JSON. (Plus, the example seems to
      show plain JSON.)

   * The specification is unclear about who receives the
     acknowledgment of the payment request. Section 2 suggests it's
     the payee (for example, "then the payment acknowledgement is
     generated locally and the payee's software is notified. "
     Examples 8 and 9 suggests the payee receives the acknowledgment.
     But the text before Example 8 says: "The payment acknowledgement
     is then relayed back to the payer:"

A. Acknowledgements

  * "... and the Web Payments Interest Group." While it is generous
   to acknowledge the IG, it is not clear to me that the IG has
   played any role in this specification.


====================
Observations

Right now the heart of the specification is the flow described in
section 2. It seems to me that the flow could be described in part
in terms of "Mediator" functionality:

 1) When payer attempts to buy something from the payee,
    payer's user agent fetches offer via HTTP.
 2) Payer's user agent invokes mediator, which prompts user to
    choose a payment application, launches the payment application,
    hands the payment application the payment request, and
    then payment processing happens
 3) Payer's payment app returns the payment response to the payee.
    (But see my question above: does the flow systematically return
     the response to the payee?)

AdrianHB has proposed a mediator spec:
 https://github.com/w3c/browser-payment-api/issues/138

I agree we should define the mediator in its own specification
including information about computing the intersection of
accepted payment methods, any requirements for user interaction,
and whatever else we deem in scope.

Then it seems that the HTTP API specification could focus on:

  - How the user agent retrieves the offer and communicates
    it to the mediator via HTTP.
  - How the payment application communications the reponse
    to the payee via HTTP.

So at a high level, I suggest:

 * We cover payment app registration and management in a separate spec.
 * We cover mediator behavior in a separate spec.

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