Edits regarding ordering based on 7 Dec WG teleconf

[ianbjacobs]

---

Preview | Diff

[marcoscaceres]

This looks good, but could we squish it into a single section and into one paragraph?

[ianbjacobs]

@marcoscaceres,

I have squished down to 1 section and 2 paras. The second para is the general statement about UX details being left to implementers.

[ianbjacobs]

I have marked this as "Do Not Merge" until discussion on 14 December.

[marcoscaceres]

The assertion:

The user agent should the user to configure the display of matching payment handlers to

Should be an example, I think.

As in:

For example, user agent could allow the user to configure the display of matching payment handlers to ...

[ianbjacobs]

@marcoscaceres, I have added an example taken from the current spec, while endeavoring to keep the text short.

[kmealey]

@marcoscaceres, @ianbjacobs, @rsolomakhin, How about for sentence 2)...From: User agents could offer some manual configuration options, such as as setting a preferred Payment Handler display order for a site, or for all sites.
To: User agents are expected to permit manual configuration options, such as as setting a preferred Payment Handler display order for a site, or for all sites.

[marcoscaceres]

Sounds good 👌

[ianbjacobs]

I have updated the proposal based on @kmealey's suggestion; I hope to be able to close this at the 14 December call.

Ian

[msporny]

A couple of observations... this PR would make the spec silent on:

1. Payment Instrument ordering and defaults. It talks about Payment Handlers, but not Payment Instruments (which are the things that show up on the UI, right?).
2. Usage patterns being used as an input to ordering.
3. Reducing clicks based on default instrument selection.
4. Merchant preferences being used as an input to ordering.
5. Minimum display expectations (icon and name).

Not defining these expectations about defaults and ordering could result in a developer implementing the spec preferring their organization's payment instruments over others by default and thinking that that is a good idea. It's this sort of "default" behavior that led to the landmark $732M EU fine where the organization knew about their corporate requirements, but whose developers failed to follow through on those requirements - http://www.nytimes.com/2013/03/07/technology/eu-fines-microsoft-over-browser.html

Suggested text:

When ordering Payment Handlers and Payment Instruments, the user agent is expected to honor user preferences over other preferences. User agents are expected to permit manual configuration options, such as as setting a preferred Payment Handler or Payment Instrument display order for a site, or for all sites.

It is expected that User agents may take usage patterns, user experience optimizations such as reducing clicks, and merchant preferences into account. It is expected that preferences will be taken into account in the following order: manually set user preferences, user preferences based on usage patterns or optimizations, merchant preferences, and default user agent preferences considered last.

User experience details are left to implementers.

It also may not hurt to mention:

Implementers are reminded that Payment Instrument ordering has regulatory implications in different jurisdictions around the world and are urged to consult legal counsel when considering Payment Instrument ordering.

I haven't address item 5 above as I doubt the implementers need to be reminded of that item.

Feel free to reword/reformat as the Editor's see fit.

[ianbjacobs]

Hi @msporny and @kmealey,

"the spec is now silent on ... Payment Instrument ordering"

I believe the specification has always been silent on payment instrument ordering within a payment application. We have endeavored to leave payment app internals up to payment app developers
and not discuss them in the Payment Handler API. We are developing a separate resource for payment app good practices:
https://github.com/w3c/payment-request-info/wiki/PaymentAppPractice

While I agree with this part of one of the proposed sentences:
" It is expected that User agents may take usage patterns, user experience optimizations such as reducing clicks..."

I don't think it is necessary to add to the specification because that's what user agent
developers do. We don't gain much by saying it. However, see a small proposal below.

Regarding this part:
"It is expected that User agents may take ... merchant preferences into account."

Payment Request API does not define a mechanism for merchants to express
preferences to the user agent. Therefore, I do not think we should mention
merchant preferences in Payment Handler API.

That is also one reason I do not support adding the algorithm. The algo defines
this order:

• Manual user configuration
• Usage patterns
• Merchant preferences
• User agent defaults

However:

1. Merchants have no way to express preferences through Payment Request API.
2. It is always the case that defaults are last for any similar algorithm.
3. It would not make sense for a user agent to override a manual
   configuration with an automatic configuration unless there were some need to
   do so (e.g., security) in which case the user agent will do it anyway.

Therefore, without the "merchant preferences" part the remaining algorithm
the rest is essentially "by definition" and would not add materially to the specification.

I don't mind changing this sentence:
"User experience details are left to implementers."

to:
"User experience details (such as optimizations based on usage patterns) are left to implementers."

Ian

[marcoscaceres]

A gentle reminder that if participants would like to support another person's position via a "+1" (or react in some other means), please use the Github-provided utilities to do so. These are located in the top-right of each comment box.

[msporny]

@ianbjacobs wrote:

I believe the specification has always been silent on payment instrument ordering within a payment application.

Yes agreed, but I'm not talking about inside a payment application. I'm talking about when the instrument is displayed to the user. See the diagram in Section 2.2:

https://www.w3.org/TR/payment-handler/#structure-of-a-web-payment-app

Payment Instruments are registered with the Payment Handler and exposed via the instruments attribute. A browser will introspect into the Service Worker and pull instruments from it, possibly changing the order to prefer their organization's payment instruments over the competition. Due to the ability to introspect, desire to reduce clicks, and order payment instruments on the screen... Payment Instrument ordering can and will be done outside of the PaymentApp as a browser optimization, right?

I get the argument that this text may be better placed in the Payment Request API (I don't care where it goes, as long as it goes somewhere). The approach taken in this spec could easily be mirrored in Payment Request.

Payment Request API does not define a mechanism for merchants to express preferences to the user agent. Therefore, I do not think we should mention merchant preferences in Payment Handler API.

There are at least 3 ways that I can envision Payment Request API will evolve based on pressure from merchants:

1. The ordering of methodData may be used by browsers as a signal for merchant preference (this is probably already how it works in most browsers).
2. Features may be added to data that are hints to browsers for merchant preferences.
3. A new payment method may be created that enables merchants to express discounts when certain payment methods are used, which are then used by browsers to sort lowest price first.

I find it highly unlikely that at least one of these won't happen if the API is successful and therefore it is worth mentioning in the specification regarding the expectations that the group has discussed. Again, maybe the better place to put this text is in Payment Request, and I'm fine with that. The reason the discussion is happening here is because there is text about display ordering in this specification and some of us in the WG believe that pointing these things out to implementers or other readers of the specification is important.

Merchants have no way to express preferences through Payment Request API.

I've just pointed out how this will probably not true now, and even if it is true now, will not hold true over time, possibly even by the time the spec hits REC. Do we know what each browser implementation does with the array of methodData? I expect most process it in order... I doubt it's randomized.

It is always the case that defaults are last for any similar algorithm.

When expressing an expected order of operations, it helps to be exhaustive so you don't make the reader guess if there are items that were not included because they were obvious to the author.

It would not make sense for a user agent to override a manual configuration with an automatic configuration unless there were some need to do so (e.g., security) in which case the user agent will do it anyway.

That assumes that the user agent provides a mechanism to set an automatic configuration for ordering of instruments, or prefers their instruments over usage. Again, I don't think anyone in the group believes that the order should be 1) user agent preferred instruments, 2) usage based instruments, 3) defaults. The group has discussed this. Let's be explicit about the expected order of constituencies. Requesting this is not new territory for W3C... we already have a W3C Priority of Constituencies:

https://www.w3.org/TR/html-design-principles/#priority-of-constituencies

We should have an equivalent for the Payments work.

Therefore, without the "merchant preferences" part the remaining algorithm the rest is essentially "by definition" and would not add materially to the specification.

Except that then we don't say anything and assume the reader has gone through the same thought process that we have (which they most likely will not have done) and therefore they don't glean the insight that we'd like them to glean by reading the text.

I don't mind changing this sentence ..
"User experience details are left to implementers."
to:
"User experience details (such as optimizations based on usage patterns) are left to implementers."

I'll try to reframe the above in a concrete set of changes to the text you have proposed in your PR (which does not address my, and possibly others, concerns):

When ordering Payment Handlers and Payment Instruments, the user agent is expected to honor user preferences over other preferences. User agents are expected to permit manual configuration options, such as setting a preferred Payment Handler display order for a site, or for all sites. When determining display preference priorities, implementers are urged to consider user preferences, then usage patterns, then merchant preferences, and finally user agent defaults.

User experience details, some of which have regulatory implications and may need corporate counsel review, are left to implementers.

[ianbjacobs]

Hi @msporny,

You raise a good point about display order of instruments in the case when user agents display those instruments. (We know that in some cases they will not, but in some cases they might.)
I have added this as a new issue:
#243

I prefer to close this pull request with the consensus language and address language for issue 243 separately (though we might end up editing the text again).

I still do not agree that we should mention merchant preferences since we explicitly do not provide for expression of merchant preferences in any specification. If it becomes possible to register
merchant preferences via Payment Request API, the we can revisit that question.

People who write software have lots of reasons for legal support, including
determining whether they can implement the entire specification. I strongly prefer not
mentioning "regulatory implications and need corporate counsel" in the specification.

Summary:

• We have consensus for two sentences; let's fold those into the spec.
• Let's address issue 243 separately. There may or may not be a need to change
  the consensus language we have so far; we can decide as we work through issue 243.
• Let's not address merchant preferences until they can be expressed normatively
  through Payment Request API.
• Let's not make broad statements that implementers need legal support.

Ian

[msporny]

I prefer to close this pull request with the consensus language and address language for issue 243 separately (though we might end up editing the text again).

-1. This PR currently removes an entire section of the spec and replaces it with two sentences.

You're deleting an entire section of the spec that says a lot about display preferences and replacing it with two sentences that do not cover the breadth of what's being removed, nor a number of the concerns that have been raised in this thread. I don't think it's appropriate to merge this PR at this time. Let's hear from others that may have an opinion about this. If I'm the only one concerned about the items I listed above, I'm happy to stand down.

As an alternative, I'm happy to have you add "Payment Handler Display Considerations" and put an issue marker in the old Section 4 stating that the entire section will be deleted once we have consensus on "Payment Handler Display Considerations".

[msporny]

I still do not agree that we should mention merchant preferences since we explicitly do not provide for expression of merchant preferences in any specification. If it becomes possible to register
merchant preferences via Payment Request API, the we can revisit that question.

"If it becomes possible" might be at any point with any one of the Payment Method specs or right after we get to REC with PR API. Feels easier to future proof... you could add (if applicable) if it makes you feel more comfortable with the language. It's non-normative, what does it hurt to include it?

People who write software have lots of reasons for legal support, including determining whether they can implement the entire specification. I strongly prefer not mentioning "regulatory implications and need corporate counsel" in the specification.

Implementing parts of the PR/PH API necessarily require a deeper need for counsel than implementing other parts of the Web Platform such as Canvas, Battery Status, or Page Visibility APIs.

[ianbjacobs]

Hi @msporny,

Regarding the legal advice, it might help to follow what the group has already done in Basic Card [1]. The text reads:

"Depending on jurisdiction, users of this specification (implementers, merchants, payment processors, etc.) can be subject to PCI DSS or other regulations. Discussion of those considerations are outside the scope of this document. "

Those who supported that text wanted specifically to call out PCI DSS since the specification is about card payments. There is no mention of "needing corporate counsel," however.

Are there specific rules (analogous to PCI DSS) that you have in mind?

Ian

[1] https://w3c.github.io/payment-method-basic-card/

[ianbjacobs]

Hi @msporny,

Regarding shrinking the text, I would say in general that's a good goal. The question is: what are we removing?

Here is what we are keeping:

• User prefs come first
• Allow manual configuration
• Two examples of manual configuration.
• Details left to implementers

Here is what we are removing (starting from section 4 and working downward)

• Part of an intro paragraph (not substantive)
• Respect payee order; removed upon @kmealey request
• Issue marker (not a part of the spec)
• One payment handling order example (origin matched? show at the top) (not substantive)
• Issue marker (not a part of the spec)
• Statement about icon and label (covered materially in 3.3.7)
• User experience hint to browsers (not substantive since just an example; furthermore, this
  text is left over from the days when we were trying to communicate what payment apps
  were about).
• Issue marker (not a part of the spec)
• Selection of instruments. We've had extensive discussions with Google and Mozilla about this
  and we know their positions. This text, too, is a holdover from the days when we were
  explaining the big picture.

This is the sort of analysis that led the editors to feel comfortable about removing the text.

For this reason, I am comfortable with the text that we've come up with and about which there is consensus among @kmealey, @marcoscaceres, and myself.

Ian

[adrianhopebailie]

+1 to minimizing non-normative text. I don't think the technical specifications are the right place to capture the WG's decision process and discussions.

[marcoscaceres]

Small typo to fix, otherwise all good.

[marcoscaceres]

typo: as as

[ianbjacobs]

Thanks @marcoscaceres for the close read.

Ian

[msporny]

I'm fine w/ compromising on: a91db52

@ianbjacobs wrote:

Are there specific rules (analogous to PCI DSS) that you have in mind?

Yes, we could point to regulations such as those set the Robinson–Patman Act of 1936 (Title 15 U.S.C. § 13): https://www.law.cornell.edu/uscode/text/15/13 or in the EU, Articles 101 to 102 of the Treaty on the Functioning of the European Union (TFEU): https://en.wikipedia.org/wiki/Article_101_of_the_Treaty_on_the_Functioning_of_the_European_Union https://en.wikipedia.org/wiki/Article_102_of_the_Treaty_on_the_Functioning_of_the_European_Union ... again, non-normative text and just enough of it to give a heads-up to developers that may not be aware of the landscape.

[ianbjacobs]

@msporny, thanks!!

@kmealey, if you are satisfied, please give a thumbs up and I'll merge the pull request. Thanks!

Ian

[kmealey]

@ianbjacobs
@msporny
If this is the final language, I am okay with it. Thank you!
"When ordering Payment Handlers and Payment Instruments, the user agent is expected to honor user preferences over other preferences. User agents are expected to permit manual configuration options, such as setting a preferred Payment Handler display order for a site, or for all sites."

[marcoscaceres]

class="informative"

[marcoscaceres]

origins instead of sites