- From: Manu Sporny <msporny@digitalbazaar.com>
- Date: Wed, 13 Apr 2016 12:46:27 -0400
- To: Payments WG <public-payments-wg@w3.org>
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. > 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.) This is a problem w/ one of the 3rd party Javascript libraries not loading correctly via HTTPS. I've temporarily downgraded that library to load over HTTP, which means you'll get errors in HTTPS mode. My hope is to eventually remove this library once we get an alternate flow diagram in the spec. Loading the spec in HTTP (instead of HTTPS) should also "fix" the problem. > 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? https://github.com/w3c/webpayments/pull/120/files#diff-e01bf2c084746b64b0dedc23f7024a10R164 > * "...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. Fixed by striking "and the selected app". https://github.com/w3c/webpayments/pull/120/files#diff-e01bf2c084746b64b0dedc23f7024a10L166 > * "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. Agreed that we should move those steps elsewhere. For the time being, I marked it with an issue marker that states the following: """ This payment app selection process should probably be moved out into a separate payment mediator specification and referenced from this specification. """ I've updated the spec to note that we should move the steps once there is a good home for them and call out the intent to move the spec text once that happens. https://github.com/w3c/webpayments/pull/120/files#diff-e01bf2c084746b64b0dedc23f7024a10R226 > * "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. I added an experimental entry in the Web Payments IG glossary so that the term would resolve across all specs. I used AdrianHB's definition from the wiki. https://github.com/w3c/webpayments/pull/120/files#diff-e01bf2c084746b64b0dedc23f7024a10L258 > * 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. Yes, payees (via payment requests) and payment apps (via the registration call) can provide an service endpoint URL that is capable of receiving payment requests (the payment request service endpoint). > * 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? At present, this is the algorithm (or rather, another way of looking at the algorithm that's in the spec): 1. Let "selectedApp" be the payment app selected by the payment mediator. 2. Let "selectedMethod" be the payment method provided by the payee and selected by the payer. 3. If selectedMethod.paymentRequestService exists, re-direct the user there (payee-based PSP). 4. If selectedApp.paymentRequestService exists, re-direct the user there (payer-based PSP). 5. Otherwise, the payment response can be generated locally (local PSP - Bitcoin and others). That said, I'd be surprised if this algorithm covers all of the payment flows we're envisioning. I expect that we'll have to rethink/revise this several times before we come up with a way to express this information in a way that's not confusing to developers and is flexible enough to cover all of our potential flows. In an attempt to make the direction more clear, I've added an issue marker with the algorithm above into the spec and a warning that the algorithm will most likely need to change. https://github.com/w3c/webpayments/pull/120/files#diff-e01bf2c084746b64b0dedc23f7024a10R258 > * "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. https://github.com/w3c/webpayments/pull/120/files#diff-e01bf2c084746b64b0dedc23f7024a10R326 > 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). > 3.2 Processing a Payment Request > > * The section title seems broad. How about "Initiating a Payment > Request"? Fixed. https://github.com/w3c/webpayments/pull/120/files#diff-e01bf2c084746b64b0dedc23f7024a10R438 > * "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. Good catch. I've updated section 3.2 to show the extra round trip and also added an issue marker noting that we may want to design the system to not have this extra round trip in there. https://github.com/w3c/webpayments/pull/120/files#diff-e01bf2c084746b64b0dedc23f7024a10R449 > * 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. Good point, I've added a step at the beginning of Section 3.3 to try and make the transition from 3.2 to 3.3 a bit smoother. https://github.com/w3c/webpayments/pull/120/files#diff-e01bf2c084746b64b0dedc23f7024a10R505 > 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.) Fixed. https://github.com/w3c/webpayments/pull/120/files#diff-e01bf2c084746b64b0dedc23f7024a10L426 > * 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:" Fixed. https://github.com/w3c/webpayments/pull/120/files#diff-e01bf2c084746b64b0dedc23f7024a10R560 > 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. https://github.com/w3c/webpayments/pull/120/files#diff-e01bf2c084746b64b0dedc23f7024a10R637 > 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. > 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've also heard people say that the payment app may be provided by the payee at the time of sale and admit that that flow throws a bit of a wrench into the works as it's not clear why the payee's payment app doesn't just register itself like every other payment app. I've tried to integrate this alternate flow into the general flow but note that it's awkward and the details haven't been thought through. One alternative is to remove this payee provided PSP app flow and wait for someone to produce a concrete example of how this would work w/ the new architecture. I would expect WorldPay or Shopify to have thoughts on this (and hope they chime in or review the spec at some point). > 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. I've left some thoughts about that here: https://github.com/w3c/browser-payment-api/issues/138#issuecomment-209537202 > 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. +1 > So at a high level, I suggest: > > * We cover payment app registration and management in a separate > spec. I'm skeptical that we can move all of registration into a separate spec but am willing to give it a shot once we have a registration mechanism outlined for the Browser API. > * We cover mediator behavior in a separate spec. My thoughts on that here: https://github.com/w3c/browser-payment-api/issues/138#issuecomment-209537202 -- manu -- Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny) Founder/CEO - Digital Bazaar, Inc. blog: The Web Browser API Incubation Anti-Pattern http://manu.sporny.org/2016/browser-api-incubation-antipattern/
Received on Wednesday, 13 April 2016 16:46:51 UTC