Merged PaymentRequest params and tweaked to address some issues

[adrianhopebailie]

Merged PaymentRequest constructor params to allow for options (only
processed by the UA) and details (passed to the payment app).
This commit proposes solutions to:
#3, #4, #15 and #18

[adrianhopebailie]

Addresses #3

[adrianhopebailie]

Also resolves #48

[adrianhopebailie]

Could add a sequence<CurrencyAmount> amount to solve issue #4

[msporny]

I'm very wary of catch-all containers such as "data". I'd rather we figure out how we do extensibility properly before punting to "generic data buckets". So, -1 to this line. The rest of the PR is looking good - still reviewing it.

[adrianhopebailie]

The separation of concerns that is introduced by this change also makes solving #1 more elegant.

[adrianhopebailie]

I believe that merging this would also solve for #49 and make PR #83 redundant

[msporny]

Yes, this is a very good step in the right direction.

[dlongley]

👍 To this PR, but note that I'm in agreement with Manu's comments.

[zkoch]

I am not a fan of providing multi currency support, especially from a UX perspective. If a merchant really wants this, they could always ask their users in what currency they want to pay before calling paymentrequest.

[adrianhopebailie]

@zkoch We have had strong support for including this.

I understand that it makes the UX more complex but that's an implementer challenge that I assumed would be embraced as a way to differentiate.

Off the top of my head I can imagine a browser having a small selector that allows the user to select their payment currency and when they do the rest of the UI adjusts to display the pricing in that currency. The selector would only be visible if the request actually contains more than one currency.

On the other hand, I don't see us having any conformance language that forces the implementer to display all currencies to the user in the app selection UI. If the browser picks one currency and displays that currency and price that is still valid as the user's option to select another currency will then be made in the app.

[adrianba]

I'm not in favour of this change. The motivation for the four arguments in the current API was as follows:

• supportedMethods - this sequence changes infrequently (and might even be hard-coded into a site). It's possible that a payment service provider might provide this data to a site. This data depends on the commercial agreements in place and what the site can handle. It is possible that payment responses passed to a service provider might not require any other code changes to the site.
• details - this is the data that varies per transactions. Most commonly this data reflects the contents of a shopping cart or basket. The site will construct this data before making a payment request.
• options - this is data that comes from the site's business needs. Do they need a shipping address? Do they want to request an email address? Etc. This data changes very infrequently and most likely requires a code change by the site to address.
• data - optional additional data that a payment method might need but that is entirely optional.

As I've mentioned before, the final data argument is the most experimental. I don't think we have much evidence yet as to whether this data is almost always required, rarely required, or sometimes required. The goal here was to keep the API simple in the cases where this data is not needed. If we have evidence to show that it is almost always needed then changing the shape here might be useful.

In general in the web platform, we have APIs that consume domain specific data rather than one large undefined blob of data. I think it is better to keep the arguments separate and consider who will change them and when.

[adrianhopebailie]

@adrianba I understand the motivations and agree they are valid but I don't believe they justify the inflexibility that results from this format.

Consider the following simple example. A new input parameter is defined for basic card payments. In general merchants will use the same value for all card payments. Today they would need to list out all of the card payment method identifiers they support in the supportedMethods array and then again list each individually in the data object with the same value provided under each.

So you have this:

var request = new PaymentRequest(
  ["visa", "mastercard", "amex"], 
  details, 
  options, 
  {
    "visa" : {
      "customDataThing" : true,
    },
    "mastercard" : {
      "customDataThing" : true,
    },
    "amex" : {
      "customDataThing" : true,
    },
  }
);

Instead of this:

var request = new PaymentRequest(
  options, 
  [
    "identifiers" : ["visa", "mastercard", "amex"],
    "data" : {
      "customDataThing" : true,
    }
  ]
);

If you multiply that out for a merchant that supports more than 3 card types and you have a horrible mess.

While I see the value in isolating data like supportedMethods and options that seldom change I would argue that a website can just as easily keep a static ("hard coded") template that contains all of this data and they will simply merge in the transaction specific data for each request. This may be as simple as adding a total and some line items.

What this proposal also addresses is the idea of "messaging" and the need to define a single JSON-serialized payment request message that is 1) not clouded with data that is only useful to the browser (like shipping options or line items) and 2) can be passed over process or network boundaries to a payment app.

I assert that it is a requirement of the API that the website has complete control over the content of the payment request that is ultimately received by the payment app. i.e.This should not be modified in any way by the user agent. This suggests that this payment request message should be passed as a single object to the API and that any other data that is only required by the user agent should be put into one or more other parameters.

[halindrome]

@adrianhopebailie said:

I assert that it is a requirement of the API that the website has complete control over the content of the payment request that is ultimately received by the payment app. i.e.This should not be modified in any way by the user agent. This suggests that this payment request message should be passed as a single object to the API and that any other data that is only required by the user agent should be put into one or more other parameters.

+1 to this. This data really needs to be compartmentalized in something that can be a "message". Personally I would like to see the message signed in some way so that the payment app knows it was not altered on the way, but I know that is unlikely so I am just going to sit on that one until I get to say "told ya' so!"

[adrianba]

As discussed on the telcon, closing this issue. Some parts of this proposal were addressed in other PRs (#158, #162). We should address multiple currency (#3) and amounts per payment method (#4) in separate proposals.