Re: Comments on Web Payments HTTP API 1.0

On 04/13/2016 10:31 AM, Ian Jacobs wrote:
> It seems that the spec seeks to define a Web service that listens
> for payment requests made via HTTP POST.

No, that's not quite the purpose of the spec.

The purpose of the spec is to demonstrate how an HTTP API-based
ecosystem operates. It defines how:

1. A payment app registers with a payment mediator via HTTP.
2. A merchant site issues a payment request via HTTP.
3. A payment mediator delivers a payment request to a
   previously registered payment app via HTTP.
4. A payment app responds to a payment request with a
   payment response via HTTP.
5. A payment mediator delivers a payment response to
   a merchant site via HTTP.

We may choose to split some of this stuff out to other specs, but since
the structure of the documents in the WG are currently in flux, it would
be better to have a complete story in the spec than break it out into
separate specs at this point in time. Once a payment apps, payment
methods, and registration spec appear, we could move some of the prose
in the spec over to those other specs.

> I can imagine this Web service being either of the following:
> 
> * A Payment App  (I think the Payment App registration spec is 
> looking for something like this; see 6.2 [1]).

That part of the payment app spec is for browser environments. The HTTP
API spec is not for browser environments (although, it could be used in
browser environments).

> * A Mediator

Yes, it could be a mediator, but remember, we're not talking about a
single web service.

> The draft spec seems to propose the latter approach.

The draft spec outlines an HTTP API ecosystem. It defines exactly how
you'd implement a merchant site HTTP API, a payment app HTTP API, and
how a payment mediator would communicate information between the two.

> The Web service could operate either locally (on the user’s phone, 
> for example) or remotely (in the cloud). (I am ignorant about the 
> extent to which native operating systems support HTTP communications
>  among apps.)

Each part of the HTTP API (payment app, mediator, merchant site) could
be implemented locally or in the cloud.

> I think the spec could useful show an example of when this would be 
> invoked.

I don't quite understand this sentence above. How could it show that?
Diagram? prose? example algorithm?

> Is this the following scenario the sort you envision?
> 
> * The user sets up a Web service that responds to payment requests. 
> This service is identified by a URL.

Hmm, no. The user installs a payment mediator that isn't a browser (for
example, in their car's computing environment). Or their car just comes
w/ a payment mediator.

> * The user installs a parking app to make payments in local parking 
> lots. The user registers the Web service (via URL) with the parking 
> app. (The user may not know the URL of the payment service if this
> is all managed locally, just like users do not know the file names of
>  things they install.)

No, the user would register a payment app with the payment mediator. The
payment app exposes a URL where payment requests should be sent.

> * On arrival, the user launches the parking app which asks the user 
> to confirm the identity of the parking lot (e.g., by typing in a 
> number, or scanning a QR code, or by confirming the location
> proposed through GPS, or some other mechanism).

On arrival at the parking lot, the car detects a parking lot kiosk that
supports web payments. How this is done is out of scope - probably some
other protocol between the car and the parking lot kiosk... but once
that negotiation happens, a payment request is sent to the car and
received by the payment mediator in the car.

> * The parking app prompts the user to pay for a certain amount of 
> time. The user confirms.

Yes.

> * This causes the parking app to send a payment request (via HTTP 
> POST) to the Web service. The user authorizes payment and the parking
> app receives the response.

Hmm, not really. The payment request is then sent to the payment app's
POST URL that was previously registered.

> * While at lunch, the parking app alerts the user that the time is 
> about to expire and prompts the user to pay for another 30 minutes. 
> The user authorizes the payment and enjoys dessert.

Yes, that could also work if the car and parking app on the phone could
communicate. Or there is a car app running on a mobile phone that takes
messages from the car and talks back to the car, which then takes
actions on behalf of the user via the payment mediator in the car.

> (A even more “IOT” scenario has parking app running in the head unit
>  of the user’s car.)

Yes, that was the scenario I was explaining above since that's a better
example of why an HTTP API is important (other than the fact that a much
larger volume of payments in the world are made via non-interactive
means than interactive means).

> If this is the sort of scenario you have in mind, then I assume the 
> primary use case is for native apps.

It depends on how you define native apps. I'd phrase it differently -
the Web Payments HTTP API's primary use case is for applications that
have Web connectivity but are not browsers. So, the subset of user
agents that are not browsers.

> I say that because if the parking app is an in-browser Web app, then
>  I would expect the app developers to use the paymentRequestAPi.

Correct.

> If the goal of the spec is to define a Web service, then I would look
> for it to address topics such as:

While that's not the goal of the spec

> * Query parameters available when invoking the Web service * Response
> codes and error conditions * Security considerations * Extensibility
> and versioning

Yes, the spec should also cover these items.

> Your draft does partially touch on these topics (in some places with
>  placeholder section titles).

Yep, with the goal of fleshing those sections out if this is picked up
as a work item of the WG.

> If the above is an accurate read of the spec, then I think it could 
> be reworked to make it much clearer that it is defining a Web 
> service, with reference to components (Mediator, Payment App) that I
>  expect to see defined in their own specs.

While the purpose of the spec isn't to define /a/ Web Service, but HTTP
endpoints that can be implemented/used by payment apps, payment
mediators, and merchant sites (which you could argue could be another
type of payment app).

I agree that we should, in time, refer to other specs like the payment
apps spec, or the payment methods spec, or a payment mediator spec (or
just the payment architecture spec that defines all of these). That
said, I would be a -1 to wait until all those specs were in place before
adopting the HTTP API spec as a WG work item.

-- manu

--
Manu Sporny (skype: msporny, twitter: manusporny, G+: +Manu Sporny)
Founder/CEO - Digital Bazaar, Inc.
JSON-LD Best Practice: Context Caching
https://manu.sporny.org/2016/json-ld-context-caching/

Received on Thursday, 28 April 2016 02:33:02 UTC