Re: [webpayments] PROPOSAL: The PaymentRequest object SHOULD NOT expose internal state information to the developer. Any design that requires developers to manage or understand the request state is a compromise in the API design that should be avoided where possible. (#64)

Are conflating the API with the messages that are passed to the API?

My assumption, when we talk about a **payment request object** in the context of the browser API, is a JSON object that contains all the data specified by the payee. This object is passed as a parameter to the browser API when a website requests a payment.

On the other hand there is a **payment request API** which accepts the payment request object as one of perhaps many parameters.

There are 2 proposals on the table about the shape of the API itself:
 1. An instantiable object of type PaymentRequest which is created for each request and exposes methods and may raise events
 1. An interface on the global `navigator` object, something like `navigator.payments` which exposes methods and may raise events.

Assuming the **payment request object** is defined as follows:
```js
var pr = {
  "currency" : "EUR",
  "amount" : "100"
};
```
A payment using 1. is made as follows:
```js
var pay = new PaymentRequest(pr, ...);
pay.show();
```
whereas a payment using 2 is made as follows:
```js
navigator.payments.requestPayment(pr, ...);
```

So it would appear to me that this proposal should read:

PROPOSAL: The browser API SHOULD NOT expose state information to the developer. Any design that requires developers to manage or understand the state of a payment request is a compromise in the API design that should be avoided where possible.

@msporny Does that sound like a reasonable amend to your proposal?

As an thought experiment, one could take this a step further and consider the UX implications of the API raising events and requiring the website to respond to these at all.

When the website calls the API it is expecting to *lose focus* and for the user to begin interacting with a native browser UI, platform UI or a payment app UI (less likely - see #55). The website will only get focus again when it receives the payment response.

Should we be defining a mechanism whereby the browser passes the execution flow control back to the website but not the user focus? 

I have heard an argument that this is all done asynchronously so it won't affect the UI but that assumes the event handled by the website and the subsequent response to the browser will not materially impact the UI. Otherwise we have a terrible user experience where either the user interface is regularly locked in a "waiting" state while the browser waits for the website to respond to the event or the UI is not locked but anything the user does after the event is fired may be lost if the response from the website renders their actions invalid. This proposal is an argument against doing the former and here's an example of the latter:

 1. User selects a shipping address
 1. Event is fired on the website to indicate that the user selected a shipping address
 1. Website sends HTTP request to server to calculate new price
 1. User is prompted to select a payment app
 1. User selects an app
 1. Payment app requests user to login
 1. User logs in with username and password
 1. Payment app prompts user to confirm payment
 1. Website gets response from server with payment request details based on choice of shipping address
 1. Website sends new payment request to browser via API
 1. UX FAIL: Browser kills payment app and prompts user to select a new payment app because the one they were currently using isn't a valid choice anymore

There are many places in that flow where the UX could be severely compromised by trying to make async requests to the website through events without returning the focus to the site or locking up the UI.

That begs the question, shouldn't we be avoiding events AT ALL if we can? And if we consider events useful for their designed purpose - notifying the website of an event as opposed to making an sync request disguised as an event - we can include them then?

An example of a legitimate event might be; notifying the website that an out-of-band request to the web server was made to get an updated payment request therefor the website may want to fetch the latest payment request from the server.

So a more bold but architecturally sound proposal would be:

PROPOSAL: The browser API SHOULD NOT raise events as a means of making asynchronous requests to the website. Events should only be used if there are actual events that it is valuable for the website to be aware of, and the only expected behavior of the website should be to ignore the event, process it or cancel the payment request.

---
Reply to this email directly or view it on GitHub:
https://github.com/w3c/webpayments/issues/64#issuecomment-179256852