Re: [w3c/browser-payment-api] PROPOSAL: A new document structure for this API (#138)

@dlongley and I had a discussion about the various specs that this group is thinking of publishing and how they all fit together. After a bit of back and forth, we arrived at this organizational structure:

<img src="https://docs.google.com/drawings/d/1pi6Edtq--FzRWtTvvkJ7ez0_c6YAalC39m-9aTHC3Jk/pub?w=1440&h=1080">

The identified goals are:

- Create a cohesive set of specifications that reflect the current direction of the group while also ensuring the proper separation of concerns.
- Ensure it's easy to write new extensions to the specifications.
- Don't publish so many specifications that it's hard for people to get their mind wrapped around the architecture.

Here are the specs and what they do:

## Web Payments Architecture

Details the Web Payments ecosystem by describing payment apps, payment mediator/agents, payment messages, and how messages are routed from payee to payer and back. Demonstrates that the architecture is flexible and doesn't define just one protocol for routing messages (HTTP /and/ browser are supported, for example).

## Core Messages

Describes the payment request and payment response messages. Integrates the payment method identifiers spec. Details how message validation and extensibility is achieved.

## Payment Method Specific Specs

Credit Card Messages and SEPA CT/DD Messages specs detail how payment request and response in Core Messages specs are augmented to provide credit card or SEPA functionality. There will be many of these specs, one for every different type of payment method (eventually).

## Payment Apps

Describes the conformance criteria for a payment app. Basically, that a payment app receives a payment request and produces a payment response.

We assert (and this may be controversial) that a payment mediator / payment agent is just a specialized subclass of payment app. A payment mediator receives a payment request and produces a payment response by routing that request elsewhere (that's the definition of a payment app, btw). The difference between the foundational definition of a payment app and a payment mediator/agent is that the latter can keep track of multiple payment apps that can process a payment and thus has registration functionality inherent in it. 

So, the beginning of the payment apps spec would talk about payment apps generically and the bottom of the spec would define a new subclass called the payment mediator / payment agent, which would have the algorithms for registration and payment app selection.

## HTTP API

The HTTP API would define how a payment mediator/agent accepts a payment request over HTTP and responds via HTTP. It would also define how payment app registration is done over HTTP.

## Browser API

The browser API would define how a payment mediator/agent accepts a payment request via a browser API call and responds in the same way. It would define how payment app registration is done via a browser. It can also have all of the user data collection bits that Google/Microsoft have proposed.

## Alternatives

To be clear, we /could/ split out payment mediator/ payment agent from the payment apps spec. We could split registration out from the HTTP API or the Browser API. I don't think we should do that until it's clear that we are going to hold up CR by doing so.

I'd like the opportunity to present this during a telecon so that the group can get their mind wrapped around what's being proposed as explaining this in an issue tracker is not ideal.

---
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/browser-payment-api/issues/138#issuecomment-210086526