Spec-Ops comments on Web Payments HTTP API 1.0

Below are my comments.  Sorry they are so terse - I was writing them on a
train...

Header Section

Add github links for repo and issues

Abstract

Define “payment apps” as an alias for “payment app”

SoTD

s/organisation/organization/

Terminology

What is [PSD] ?



Payment Flow Overview

Issue 2: Yes, please change the example to a more traditional credit card
transaction.  I think this will help with adoption.

Also, please try to present the flow diagram using ordering similar to that
from the Flows Taskforce (and possibly using Plantuml)

Issue 3: I am not super comfortable using a 402 response.  It feels like
something we need to discuss with the HTTP working group.  Also, this flow
doesn’t envision a model where I am just ready to send a payment.  I have
to make a request that fails in order to trigger the transaction.  That
feels weird.  Not that I have a concrete suggestion about how to trigger
the payment protocol without explicit initiation. Just that it feels weird.

Step 1 has “request” in courier to imply that it is a known thing.  But it
isn’t really defined. I assume it is some message structure. Please include
a reference.

Issue 4: I am fine talking about a payment mediator in this spec because it
is part of the conversation.  It has to be defined somewhere.  A payment
mediator spec would be something that could easily go through CR because I
would know how to test that.

Step 4.3 implies interaction.  I don’t think this should be required (and I
know it is not) but a casual reader might think that it is.

Step 5: s/e.g./e.g.,/


Step 5 also says “and the payee’s software notified”.  This should be its
own step.

Step 6.1 mentions request again.  It should be a reference back to a
definition of the request.

Step 7.1 mentions request but not in courier.  Fix the font and make it a
reference back to a definition.

Issue 6: I don’t think the response code is important.  While this IS an
HTTP API, the actions of the API should largely be informed by the
messages, not the response codes and headers.

Issue 7: I agree with Melvin. A 402 is just weird (see above).

Detailed Payment Flow

Change the example to be a more traditional and simple payment (CC PAN +
CVVS or whatever).

Also, all of the examples are too wide to read when printed.  We should
reduce the font size of all the examples in a print media selector.

Step 2: Retrieval of a Payment App seems misleading a bit.  It didn’t
retrieve the payment app. It retrieved a definition of how to access a
remote payment app. Also, it feels to me like this does not accommodate any
sort of payment app that would have native code that needed to be installed
on the payer’s machine.  If so, and if that is the intent in this
ecosystem, we should say that.

Initiating a Payment Request

Step 2: The model does not seem to allow for a “buy” button in a native app
that would just start a transaction. (I understand that I could force one
by attempting to retrieve a resource to which I don't have access.)  Why
not?

Step 4 (or elsewhere): There should be a reference to the core messaging
spec.

Example 9: I know this might be out of scope, but I would like that message
back to be signed in some way so I *know* it was not messed with by the
mediator.

Issue 11: Is there a way to use a profile on application/json to indicate
the schema / context that applies to the message? This would help with
interpretation and validation.


-- 
Shane McCarron
Projects Manager, Spec-Ops