New Architecture Proposal

[adrianhopebailie]

A new proposal for the architecture document.

This is in line with the discussion at w3c/payment-request#138

This is intended to be a REC not a Note and the browser API would have a normative reference to it.

[msporny]

+1 in general for this Architecture document (based on a quick read). It paints a much clearer picture of the architecture than the Payment Request Architecture document. I'd be interested in volunteering to do editorial work on it.

[ianbjacobs]

-1 for this proposal. I think it mixes levels.

I support an "overview" document that provides:

• Information about what the user experience will be
• A big picture of the key roles that are involved, notably mediator and payment app
  (The flow diagram, which I have some issues which, is helpful in that regard.)
• An explanation of the set of specs that define the space.

This proposal does some of those things, but also does "too much."

All the bits about computation and processing should not go in an architecture document.
Those are intended for software. (I also have issues with those descriptions, but I'll
make those comments separately since I think they belong in a different spec or specs.)

Another notes: There is a glossary of terms, but then terms are redefined multiple times throughout the specification.

I think we need an overview that explains to people the pieces and how they function together at a high level. Specific instructions (especially if related to conformance) belong in a different document.

Ian

[adrianhopebailie]

@ianbjacobs said:

I support an "overview" document that provides:

This is not intended to be an "overview" document. It is a technical document that defines the primary roles in the architecture (mediator and app) and the key concept of a payment method.

This is intended to be a REC track document (not a note). There should be separate documents that specify how to implement these roles in specific deployment scenarios and this should be a normative dependency of those.

The If you feel we still need an "overview" document then that should be a separate WG note titled something like "Overview" and include content such as:

• Information about what the user experience will be
• An explanation of the set of specs that define the space.

With regard to:

Specific instructions (especially if related to conformance) belong in a different document.

I disagree. We need to record somewhere the specifics of how a conformant payment app and a conformant payment mediator must behave. We can repeat this for every implementation specific spec or have this in a single place and refer to it from those implementation specific specs.

[ianbjacobs]

@adrianhopebailie ,

This is not intended to be an "overview" document. It is a technical document that defines the primary roles in the architecture (mediator and app) and the key concept of a payment method.

Maybe we are simply using terms differently:

1. I would like an overview document that explains (in non-technical terms) what problems we are addressing, the capabilities we offer to do so, and how they are organized.

2. I also would like technical documentation to which software conforms.

Those two things should not be mixed.

We need to record somewhere the specifics of how a conformant payment app and a conformant payment mediator must behave.

Agreed. That's the second document.

Ian

[adrianhopebailie]

Agreed. That's the second document.

This proposal is the second document. I think some of the confusion comes from combining the payment app and payment mediator roles in one document but I think that having hundreds of documents is a mistake.

Based on some of the comments from @dret on w3c/payment-request#138 I wonder if this document shoudl also be the normative reference for what a payment method is and how identifiers are defined?

[ianbjacobs]

@adrianhopebailie wrote: "This proposal is the second document. I think some of the confusion comes from combining the payment app and payment mediator roles in one document but I think that having hundreds of documents is a mistake."

I do not believe we will have hundreds. This diagram:
w3c/payment-request#138 (comment)

suggestions:

• 2 api specs (paymentRequest, HTTP)
• 2 specs for mediator/apps. As we discussed, I still think 2 might be better since different audiences (e.g., browser developers v. payment app developers) but I don't mind experimentation to try to come up with one.
• N payment method specs.
• 1 payment method identifier spec
• 1 architecture document

... I wonder if this document shoudl also be the normative reference for what a payment method is and how identifiers are defined?

How about this: let's keep it in its own document for now and then determine where the content should go after we understand better (1) how much content that turns out to be and (2) whether the evolution of the mediator/app spec really suggests that identifiers should be included...or not.

Ian

[adrianhopebailie]

let's keep it in its own document for now and then determine where the content should go after we understand better (1) how much content that turns out to be and (2) whether the evolution of the mediator/app spec really suggests that identifiers should be included

There is already a section on Payment Methods in this document because it's necessary to complete the picture which suggests (to me at least) that this is a logical place to put it.

[mattsaxon]

@adrianhopebailie

thanks for writing this up, and sorry its taken me so long to get around to reviewing it. I am overall happy with the proposal and support its inclusion into the WG. Below are my comments;

1. The definition of a payment request as a request from the payee to be paid removes the ability for unsolicited payments, e.g. donations. We shouldn’t remove the possibility in the architecture for a payee to offer up payment for a particular service, e.g. a ‘bid’ or ‘donation’. So for example the stipulation of what to pay might not be appropriate in all cases.
2. I think another diagram showing the roles and how they interact (not just sequence) would be useful, this could then cover interactions as a higher level and so be wider that the Payment Request Flow diagram such things such as registration.
3. The architecture doesn’t talk about invoice/receipt processing, what role(s) is the architecture are responsible for this?
4. Similarly, payment “assistance” such as shipping address information capture is not discussed.
5. I think user-agent (in the wider than browser sense) is not covered, we perhaps need something that covers what sets up the communication between a payee and a mediator.
6. I think the diagrams of the document map discussed in in issue Gh pages #138 would be useful to include too.