Comments on Payment Request API

Adrian, Zach,

We have put pull requests on hold while the repo migrates to the WG.
When you have time, here are comments on the 25 February draft [1].
Many of the comments are editorial.

Ian

[1] http://wicg.github.io/paymentrequest/specs/paymentrequest.html

===========
Status section

 * "minimal integration". What about instead: "a uniform approach
   to integration."

1. Introduction

 * s/is a frustrating/is often a frustrating/

 * "to create good checkout flows that support various payment schemes."
   Do you mean here: "to create a straightforward and consistent checkout
   flow across a variety of payment methods"?

2. Conformance

 * The first and third paragraphs are duplicates.

4. PaymentRequest interface

 * s/A web page/A web page (or web application)/

4.1 PaymentRequest constructor

 * "If the name of any top level field of data does not match one of
   the payment method identifiers in supportedMethods, then throw a
   TypeError. "

   Question: what if you have more than one instance of a payment
   method identifier?

4.2 show()

 * "Let acceptedMethods be the sequence of payment method identifiers
   request@[[supportedMethods]] with all identifiers removed that the
   user agent does not accept."

   The user agent does not filter payment method identifiers. Perhaps
   you meant:

   "Let acceptedMethods be the sequence of payment method identifiers
   request@[[supportedMethods]] with all identifiers removed that the
   do not match payment methods of the user's registered payment
   applications."

   (Note: We had interesting discussion about payment method identifiers
    at the FTF meeting, including questions about hierarchical
    identifiers, etc. It would be good to add an issue in the payment
    method identifier spec about whether we should have those in
    V1 (or later or not at all).)

4.3 abort()

 * "The abort method may be called if the web page wishes to abort the
   payment request after the show method has been called and before
   the [[acceptPromise]] has been resolved."

   I suggest moving the examples from 13.4 to here:

   "For example, a web page may choose to do this the goods they are
   selling are only available for a limited amount of time. If the
   user does not accept the payment request within the allowed time
   period, then the request will be aborted. "

4.4 State transitions

 * I thought this section should come before the show() description.
 * Two methods are shown (show, abort) but complete is not. Is there
   a reason? If the answer is "complete is about the response" that
   makes sense, but it would be nice to enhance the diagram to
   show the states of the request and the states of the response
   to get the overall picture.

5. CurrencyAmount

 * I believe that should read "CurrencyAmount dictionary" as other
   sections are labeled.


6. PaymentDetails dictionary

 * "The user agent MAY not validate that this is true. " This is unclear
   (and not good RFC 2119 usage). It should either be "MUST" or
   "the user agent is not required to validate that this is true."

 * s/that the use may choose/that the user may choose

 * "If the sequence is empty, then this indicates that the merchant
   cannot ship to the current shippingAddress." Please restate this
   in terms of user agent compliance rather than merchant intent
   (which is not relevant here). Proposed:

   "If the sequence is empty, then the user agent MUST NOT display
   shipping options."


 * "If the sequence only contains one item,"

   What if the sequence includes more than one item? (What's the error
   handling?)

7. PaymentOptions dictionary


 * "If this value is not supplied then the the PaymentRequest behaves
   as if a value of false had been supplied. "

   I think this statement is unnecessary given the WebIDL. I think there's
   no harm in deleting it.

 * Please specify how unrecognized options are handled by the user agent.


10. ShippingOption interface

 * I believe that should read "ShippingOption dictionary"

11.1 complete()

 * s/progress of a tranaction/progress of a transaction/

12.2 PaymentRequestUpdateEvent

 * Add "interface" to the title

 * "If the web page wishes to update the payment request then it
   should call updateWith and provide a promise that will resolve with
   a PaymentDetails dictionary containing changed values that the user
   agent SHOULD present to the user."

   First, the first "should" be an RFC2119 SHOULD.

   The second SHOULD could be a MUST, at least in some cases.  For
   example, if the UA has already displayed information to the user,
   and the information is updated, it seems like a bug to not display
   the update.

 * "Only one update may be processed at a time."

  That is not a clear requirement since I don't know what "at
  a time" means. Here are some options:

    - While target@[[updating]] is true, the user agent MUST
      ignore other update events.

    - While target@[[updating]] is true, the user agent MUST
      queue any update events for subsequent processing.

    - While target@[[updating]] is true, user agent behavior
      is undefined if the user agent receives new update events.

  I don't have any preference; just wanted to signal that this can
  be made clearer.

13.1 Shipping address changed algorithm

 * s/It MUST/The user agent MUST/
 * delete "run the following steps"

13.3 PaymentRequest updated algorithm

 * s/It MUST/The user agent MUST/

 * "Only one update may take place at a time."

   Please specify more clearly; see earlier commentary

 * "This should never occur."

   Please specify in terms of user agent behavior, whether it is
   error handling, or stating that user agent behavior in this case
   is undefined.

 * "The user agent user interface should ensure that this never
   occurs."

   Earlier in the spec, there is this text: "The user agent SHOULD
   disable any part of the user interface that could cause another
   update event to be fired." Please change the text in this case
   to say something similar about disabling the UI.

 * "Queue a task to fire an event named name of type event at request. "

   - Is "queue a task" necessary?
   - does "of type event with request" make more sense?

13.4 User agent delegates payment request algorithm

 * "A user agent may not always be able to abort a request. For
   example, if the user agent has delegated responsibility for the
   request to another app. To support this situation, the user agent
   must run the User agent delegates payment request algorithm."

   Suggest:

   "When a user agent cannot abort a request (e.g., it has
   delegated responsibility to another app), the user agent MUST
   run the User agent delegates payment request algorithm."


 * "The user agent user interface should ensure that this never occurs. "

   This appears twice in this section. Could this text be aligned with
   similar text (see above) about user interface requirements?

   Also, I find the pairing of "should" and "never" to be suboptimal.
   If you end up saying "SHOULD" then please drop "never".

13.5 User accepts the payment request algorithm


 * s/It MUST run/The user agent MUST run/

* Please align these with other similar edits:

  - 2. The user agent user interface should ensure that this never occurs.
  - 3. The user agent user interface should ensure that this never occurs.
  - "This should never occur. "

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