Should a payment request be just data, or a programmable object?

[msporny]

Migrating from w3c/webpayments#36:

The paymentRequest API asserts that a payment request is a programmable object:

http://wicg.github.io/paymentrequest/specs/paymentrequest.html#paymentrequest-interface

that is instantiated like so

var payment = new PaymentRequest(supportedInstruments, details, options, schemeData);

and can have methods called on it like so:

payment.addEventListener("shippingAddressChange", function (changeEvent) {
    // Process shipping address change
});

The Web Payments CG's Browser API asserts that a payment request is just data:

http://wicg.github.io/web-payments-browser-api/#processing-a-payment-request

and that data is processed by functions:

var request = {
  type: 'PaymentRequest',
  description: 'Payment to ExampleMerch for widgets',
  acceptablePayment: {
    paymentMethod: 'https://w3id.org/payment-methods#Visa',
    paymentAmount: {
      amount: '4.35',
      currency: 'USD'
    }
  }
};

// request payment and get a promise that will resolve to
// a payment acknowledgement
var payment = navigator.payment.request(request);

// called when the payment request has been processed
payment.then(function(acknowledgement) {
  // payment request was at least partially processed, do something with the
  // acknowledgement, such as check its approval code or forward an approval
  // token to actually execute the payment
}).catch(function(err) {
  // payment request failed
});

These are two different general design approaches for the browser API:

1. There is data, and functions act on that data (Web Payments CG approach).
2. There are objects that consist of data, and verbs that hang off of those objects (paymentRequest approach).

So, what is our design approach for the browser API?

[adrianba]

The design of the PaymentRequest API allows events to be fired in any order. A promise can only be fulfilled or rejected. I recommend that this issue be closed.

[adrianhopebailie]

@adrianba it's unclear to me how your comment relates to the question being asked. I assume you mean that the current design is required because it uses events to notify the website of user choices with regard to things like the shipping address and therefore an event emitting object is required.

I don't dispute that, I agree that we do need a valid event emitter to support the current design.

However, my understanding of the crux of this question is whether:

1. The website should construct the payment request data in the exact form that it will be passed to the payment app OR
2. The website will pass data to the PaymentRequest object in the form of constructor arguments and/or through property setters (i.e. in fragments) and the payment request that is passed to the payment app is some serialized version of the PaymentRequest object.

In my proposal in PR #133 I have used your existing model of a PaymentRequest object but made a clear separation between data passed in that is consumed and used by the user agent (options) and the payment request that is passed on to the payment app (data). So, I think we can still have the API shape you have designed but pass the core payment request (minus the shipping data etc) as pure JSON data.

[adrianba]

I'm trying to answer the question raised by this issue. i.e. "Should a payment request be just data, or a programmable object?" and consider whether this is an issue we need. I don't believe that issue #47 helps us make progress and I recommend that we close it.

[adrianhopebailie]

This issue has nothing to do with events vs promises which is all your comment discussed.

This issue has to do with the idea of "messages" and the need to encapsulate the full content of a payment request as a single JSON-serializable object that can be passed across process or network boundaries.

The current design splits all of the data that must be passed to the payment app among a variety of parameters so it is unclear how a JSON-serialized payment request would be created from a PaymentRequest object or what it would look like.

The question at hand is whether or not it would be better for there to be a clear separation of concerns in the API so that the payment request is constructed entirely by the website as a single pure data object and passed to the PaymentRequest constructor in the same form the website expects to be passed on to the payment app.

I don't consider the other functions of the PaymentRequest object (such as emitting events) as the issue at hand because, as you say, that's the design we have chosen to adopt.

[adrianba]

I was comparing the code snippets in the original comment. In the first snippet, which calls the PaymentRequest constructor, the only programmable object is the PaymentRequest object. In the second code example, there is no programmable object. A promise is returned. Since the issue asks whether a programmable object should be involved I concluded that the comparison was between code that returned an object and code that didn't but returned a promise. Hence my comment.

All of the arguments to the current PaymentRequest constructor can be serialized as JSON. In fact that is a requirement for some of them. None of them are "programmable". There is also a separate issue (#15) about combining arguments into a JSON serializable object.

As you say, we've already adopted a design with a programmable object. Another reason I think this issue should be closed.

[adrianhopebailie]

From the discussion it seems this issue is unclear on what is being addressed:

1. Is the issue querying the use of events vs promises?
2. Is the issue highlighting the need to have a JSON-serializable payment request message that is passed to API (and which the user agent passes on to the payment app) rather than an opaque object with no clarity on how a JSON-serializable payment request message is extracted?

With regards to 1. the current API uses events and the motivations for this provided by @adrianba appear to be uncontested. There is another issue, #51, which discusses the option of a more fluid API shape that is a better place to address this discussion of shape and preferred patterns.

With regards to 2. this is discussed and addressed in the comments on #133.

I am closing this issue and requesting that if there are other issues that were intended to be encapsulated here they be logged as new issues with concrete proposals for addressing them.