Re: Comments on Web Payments HTTP API 1.0

> On Apr 13, 2016, at 11:46 AM, Manu Sporny <> wrote:
> On 04/12/2016 02:44 PM, Ian Jacobs wrote:
>> Here are some initial comments for the discussion about the Web
>> Payments Working Group taking this on.
> Thanks for taking the time to review the spec, Ian. Responses to your
> questions/concerns below.

>> 2. Payment Flow Overview
>> * "The payee provides a location". I prefer not to use location.
>> What about "identifies a service" ?
> I don't know if "identifies a service" is correct. The payee is
> providing a resource URL where the payer client can fetch a payment request.
> I changed this to "provides a URL"... does that work for you?

Ok for now.

>> * "6.1) The payment agent". That term is not defined.
> Changed to "payment mediator" throughout the spec (perhaps temporarily).
> I'm a bit concerned about the terminology - I still think "payment
> agent" is better, but defer to the consensus of the group.

The Architecture wiki has used Mediator for some time, and I believe we

>> * "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.
> Yes, I understand your concern. We went back and forth on this quite a
> bit in the WPCG.
> The shaky consensus at the time was that 200 is the right thing to do as
> the message was processed successfully (that's what the 200 is referring
> to). The result of processing the message, however, has a whole load of
> nuance that is very dependent on the payment method used.
> For example, what should the HTTP code be in the following cases:
> 1. Funds transfer was initiated and completed. Clearly 200, right?
> 2. Funds transfer was initiated, but network delay may cause it
>   to fail at a later point in time (ACH, etc.). 102 or 202?
> 3. Request for subscription was noted, but no funds were moved. 200?
> 4. Payment submitted to network, but network didn't respond with
>   an auth code. 504?
> 5. Cryptocurrency payment was submitted to network but a fork has
>   been detected and it is unclear if we're on the winning or losing
>   fork. 102 or 202?
> I don't think there are enough HTTP status codes to try and enumerate
> the potential outcomes and I'm not sure we can make the call on whether
> or not the processing of a payment request was "successful". In some
> cases, it's up to the payee to decide if it was successful or not (like
> waiting on a certain number of acknowledgments from a blockchain, for
> example).
> I have added an issue marker explaining this in the specification in an
> attempt to draw more attention/opinions on the matter.

+1 to fleshing out response codes; that is linked to my follow-up comments about what I imagine
should go in this sort of spec:

>> 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).
> I don't disagree with that general idea, but I do question if we'll be
> able to do registration using one set of algorithms for browser and
> non-browser environments. At present, I assert that the mechanism for
> registration in browser and non-browser environments is different enough
> to warrant two algorithms (or at least, we will end up with /some/ text
> about registration in the HTTP API spec).

I think a note indicating that there is a desire to have a single payment app registration
description would help.

>> 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.
> The IG worked on the capabilities document for quite a while and many of
> those concepts are reflected in this document. I've reworded the
> acknowledgements section to add the Web Payments WG as well.

My suggestion is to drop references to the IG and WG because I donít
believe the involvement has been significant enough to merit mention.

>> 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.
> I know what you mean, but we should be careful about calling this an
> "offer". That's something else. In this iteration of the HTTP API, the
> payer's user agent is fetching a payment request (which may, in the
> future, also contain an offer - which is a digitally signed offer of
> sale listing product details, terms, etc.).
>> 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
> +1, although I'm a bit concerned about having so many specs that it
> becomes difficult to navigate them by developers.

I think each spec should target the people who will implement it. That
will help reduce noise and make the specs easier to consume, even
if they are modularized. But I agree we should not arbitrarily create
a large number of specs.

>> 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?)
> Not always (maybe), but we don't talk about that in the spec yet. I've
> heard some allude to this concept that there may be a way for payment
> apps to communicate out-of-band via a chatty protocol with payees. It's
> not clear to me if we want to do that even though I can see the benefits.

I donít think we should standardize how (or when) payment apps communicate
with the payee. Thatís their business and is not part of the payment
flow that I believe we are attempting to standardize.

Thanks, Manu.


Ian Jacobs <>
Tel:                       +1 718 260 9447

Received on Thursday, 14 April 2016 13:52:30 UTC