[webpayments] What is the appropriate conversational pattern for the API? (#55)

i.e. Should the API be an open channel for communication between the Website and Payment App or should it simply accept a request and return a response and all other comms must be done out of band?

This question has been raised implicitly in a few other issues such as https://github.com/w3c/webpayments/issues/41 and https://github.com/w3c/webpayments/issues/39.

It is also surfaced as a requirement of the API due to the discussion around shipping, tax and line item details.

In the case of the browser API the options are:

__Option 1__
The API accepts a payment request and focus moves to the Payment App. The Payment App will return a payment response to the Website and the Payment App will close.

```javascript
navigator.payments.requestPayment(...)
.then(function(paymentResponse){
  //Process the payment
});
```

_Pros_
 * Simple API. All data is passed in a single request
 * Simple state flow. The Website passes control to the API (and therefor the Payment App gets focus) and when it get's back a response it is able to process it. No need to track state or listen for events.
* Loose coupling. A simple request/response flow means the coupling between the Website and Payment App is loosely defined.
* Simple UX. The user experiences a single focus change as the Payment App is brought into focus and then closed when their interaction completes.

_Cons_
 * Inflexible. All possible pricing options for all supported payment methods must be included in the request which means the request grows exponentially with each new option or variation of the offer.
 * Static. It's impossible to adjust the offer/request based upon the user's input such as shipping address, loyalty club membership, coupon code etc.

__Option 2__
The API accepts a payment request and focus moves to the Payment App. Certain actions in the Payment App will cause a message to be returned to the Website during which time the Payment App UI will remain in focus but will be in a non-responsive or waiting state until the Website responds to that message and the Payment App can continue processing based on the Website's response. Finally the Payment App will return a payment response to the Website and the Payment App will close.
```javascript
navigator.payments.addEventListener("paymentAppMessage", function (msg) {
  //Process msg and update payementRequest
  navigator.payments.updatePaymentRequest(...);
});

navigator.payments.requestPayment(...)
.then(function(paymentResponse){
  //Process the payment
});
```

_Pros_
 * Infinitely flexible. Websites can develop innovative offers with dynamic pricing and complex interactions with Payment Apps
 * Smaller messages. The initial request can be much simpler.

_Cons_
 * UX complexity. Either the focus continuously switches between the Payment App and the Website (terrible UX) or the Payment App (while in focus) becomes unresponsive and enters a wait/loading state while waiting for the Website to respond to a message.
 * Asynchronous API with synchronous messaging. The Website and Payment App send messages asynchronously however the behavior of the two components is very dependent on the content of the responses they get so the processing they can do in parallel is very limited.

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