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

[msporny]

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 (see example in link above for a clear picture of what this looks like in practice).

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?

[msporny]

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

I assert that our design approach should be: "There is data and functions act on that data"

There are at least three reasons to take this approach:

1. It helps us clearly delineate the payment messages from the things you can do with those payment messages (this helps us more easily use the same messages for the HTTP API and the browser API and align w/ ISO20022).
2. It simplifies the browser API and thus reduces the cognitive load on developers as it's clear that you have payment data and things you can do with that payment data.
3. It avoids unnecessary complexity in the browser implementations by making the browser just a payment message router instead of exposing a payment request state machine to the payee.
4. It's more flexible, as a data-only approach decouples behavior from the data.

There is much more on the downsides of object-and-verb API design here:

http://steve-yegge.blogspot.com/2006/03/execution-in-kingdom-of-nouns.html

[dlongley]

See also: Rule of Least Power.

[burdges]

It's fairly hard to imagine what a payment request gains from being code. If the payee has say preferences about instruments, then that could be encoded fine in data. It's easy to imagine web developers botching up payment requests though.

[msporny]

Here's a proposal, since there doesn't seem to be any push-back on the issues list:

The PaymentRequest object will not have code attached to it. It will be a pure data object (with no added Javascript functions) as demonstrated in: http://wicg.github.io/web-payments-browser-api/#processing-a-payment-request

[msporny]

Let's also not forget that XMLHttpRequest is problematic API partially due to the fact that it stores state (like the PaymentRequest API proposal) and managing that state machine has led to code being more complicated than necessary for developers.

The problem got so bad that there is a new Fetch API proposal that attempts to cut down on many of the state-machine related issues (among a slew of other non-state-machine-related issues).

[adrianhopebailie]

Moved @msporny proposal to it's own issue so that the discussion may continue on this thread if the proposal is not accepted.

[msporny]

Migrated to w3c/payment-request#47