Should the merchant be able to request your email and recipient phone number

[adrianba]

This issue comes from WICG/paymentrequest#16 and was discussed at the F2F.

E-mail address is commonly gathered to send an order acknowledgement. Recipient phone number is often required by shipping companies.

The questions is whether this information should be shared with the merchant: always, optionally when requested, or never.

[mattsaxon]

I think this information should be able to be shared and the privacy should be configurable by the user, so for being able to set a preference that contact details are shared when payments are made if requested.

A further note is that IG use-case 6.4.2: Electronic Receipts, requires that we make provision for receipts to be sent to users in this phase (roadmap phase 1)

[adrianba]

I think this information should be able to be shared and the privacy should be configurable by the user, so for being able to set a preference that contact details are shared when payments are made if requested.

Can you expand on your proposal? How granular is this? Can the user choose not to share information? What should the spec say?

[adrianhopebailie]

In TAG review @triblondon said:

Yes. Otherwise you will end up with a paymentrequest flow leading into a conventional webform to collect all the data the PR API is failing to deliver. Email and phone number are really obvious and will be needed by lots of merchants.

[adrianhopebailie]

If we are going to allow the website to request multiple different pieces of data then the mechanism for doing this should be more generic and extensible to accommodate new items in future.

Instead of:

{
  "requestShipping": true
  "requestEmail": true
  "requestPhoneNumber": true
}

We should have:

{
  "requestUserInfo": ["postalAddress", "email", "telephone"];
}

Refs:
https://schema.org/PostalAddress
https://schema.org/email
https://schema.org/telephone

[ianbjacobs]

Hi @adrianhopebailie,

Can you help me understand why one form is superior to the other in terms of extensibility? (The latter does require fewer characters.)

From a programmer perspective, I agree there is something more elegant about simply referencing a symbol than saying "symbol: true" but perhaps the JS crowd prefers the former approach.

Ian

[triblondon]

+1 to the tokens approach. This has a number of advantages:

• Easier to remember (arguable)
• Easier to assemble dynamically from server side script
• Implies greater extensibility: if there were 100 different user data
  aspects, there would probably be a much greater consensus on tokens as the
  correct syntax

[kirkalx]

Do we need separate requireUserInfo and requestUserInfo settings? Perhaps the scope of that is getting beyond payments and more to the relationship/trust between merchant and customer...

[msporny]

Perhaps the scope of that is getting beyond payments and more to the relationship/trust between merchant and customer...

Yes, we're starting to build a generalized customer relationship API at this point, which is exactly why we objected to this collection of customer information in the "payment request" interface in the first place. The Working Group is just not going to be able to say "no" to most requests for collection of customer information (what about billing address? What about postal code only? What about discount card number?). We're currently sliding down that particular slippery slope.

[mattsaxon]

+1 to the tokens approach, I've suggested a similar approach for info to payments apps here for basiccardpayment

#114

[msporny]

the mechanism for doing this should be more generic and extensible to accommodate new items in future

While I disagree that we should be creating a generalized customer information request API, it looks like a few in the group are determined to do it anyway, so we might as well do it right.

+0.5 for @adrianhopebailie's proposal. The Web Payments Community Group's Checkout API spec had a mechanism that I found easier to parse (as a developer reading the code) than @adrianhopebailie's proposal above via the .send() and .request() customer info calls:

http://wicg.github.io/web-payments-browser-api/checkout-api.html#the-checkout-interface

which would look something like this in practice:

var paymentRequest = ...;
paymentRequest
  .send('paymentItem', paymentItems)  // send line item estimate to UA
  .request('shippingAddress')               // request shippingAddress from UA
  .request('email')                                 // request email from UA
  .request('phoneNumber')                   // request shippingAddress from UA
  .addEventListener('shippingAddressChange', shippingAddressChanged)
  .start()                                               // start the UI
  .then(finishRequest);                      // UI has collected the info

you could even reduce it to:

paymentRequest
  .request(['shippingAddress', 'email', 'phoneNumber')

The benefit here over what @adrianhopebailie is proposing is that we don't make the payment request hold stuff that's not really about the payment request. That is, requesting an email address doesn't really have anything to do w/ the request for payment. It's just information that you'd like to gather from the customer. It feels like the payment request object is turning into a huge grab bag of payment UI configuration data.

I'd also like to underscore that we're falling into the trap of designing high-level APIs (checkout experience) instead of focusing on the low-level ones (simple request for payment) first, which @jakearchibald warned us against (as have many other folks that have designed browser APIs in the past).

[msporny]

@djackso3 wrote in #27

I believe that there is reason that all three (shipping address, billing address, KYC address) ... may need to be part of the protocol because of the fluidity for people with various reasons to maintain a shipment location for goods and "letter" or USPS location for "billing".

So add one more to the list of requests... I know this issue is supposed to be about just email and phone number, but that the options that are being requested are expanding rapdily is not a good sign (and is why we've kept saying that a verifiable claims API is a better fit for this sort of stuff).

What about personal phone? Work phone? personal email? work email?

[dlongley]

What about personal phone? Work phone? personal email? work email?

What about proof of age (or just self-asserted age)?

[djackso3]

I left this open only to those addresses which are commonly used for verification. Should that change to this list or a subset -- sure! We could include. But I had the specific examples that I wanted to share because of lack of standard ... And I am trying to keep separate the eComm v Payments flows ...

[ianbjacobs]

The question remains: what is required for adoption? I doubt it is a long list of information.

[dlongley]

I think these examples are just showing that there's a missing primitive here for collecting basic verifiable claims. If we're going to collect anything here, I'd prefer us to keep it to a very minimal set and then wait on a verifiable claims WG to help solve the other use cases.

[adrianhopebailie]

@ianbjacobs
Using a list of tokens means the API spec does not need to change in future for new types to be added.

I believe that we should approach the conformance around this functionality as a "best effort". In other words some browsers will be able to gather some data and others won't but we shouldn't have a hard-coded list that they MUST define UI for.

In the same vein, the flow must fail gracefully if the browser is unable to provide certain data and the request to get the data should either be passed to the payment app or left to the website to get after the payment response has been received.

If the payment request should not be passed to the payment app at all without the data having been captured then we need to handle that case too.

[adrianhopebailie]

I want to highlight that the data being requested here is intended to be gathered by the browser BEFORE the payment request is passed to the payment app.

Effectively there are two channels between the user and the website:

1. website -> browser -> user (interactive)
2. website -> browser (purely as proxy) -> payment app -> user

In PR #133 I have made this distinction clearer so that we don't corrupt the payment request with data requests that are part of the "streamlined checkout flow". (Think of it as the Web Payments CG Checkout API Lite).

What we get from this separation is the ability to distinguish between:

1. Data that is passed to the browser to improve the UX (line items) and request data that the merchant requires.
2. Data that is passed to the payment app because it is required for processing the payment.

I would consider @djackso3 's request for KYC data, shipping data and billing data to be something that is required for the processing of the payment and also something that may or may not be required depending on the payment method.

[mattsaxon]

The distinction between these channels would be clearer if you refered to the 'mediator' in the second channel. Separation of concerns between UA and mediator needs to be clear in our thinking even if we conflate the implementations.

[adrianhopebailie]

The distinction between these channels would be clearer if you refered to the 'mediator' in the second channel. Separation of concerns between UA and mediator needs to be clear in our thinking even if we conflate the implementations.

This is a good point but...

1. The UA and mediator are not different roles. The UA assumes many roles and one of these is that of mediator.
2. This is a UA focused spec so in most cases I'd actually talk about a UA (not a mediator)

What this suggests is that we should split out a bunch of the browser API spec into a generic mediator spec that defines the conformance criteria for a mediator. The browser API spec would then reference that document and define the specific behavior of a UA (as mediator) including the API it exposes and state changes etc.

[ianbjacobs]

@adrianhopebailie,

Using a list of tokens means the API spec does not need to change in future for new types to be added.

I don't think I agree. If you want to change what it means to conform (by adding a new feature) you need to revise the spec.

So I think the difference is only syntactic. I happen to like the list of tokens, but want to know whether that's a pattern that is preferable for JS developers.

I believe that we should approach the conformance around this functionality as a "best effort". In other words some browsers will be able to gather some data and others won't but we shouldn't have a hard-coded list that they MUST define UI for.

If we take that approach, it will be (even more) important for user agents to declare programatically what features they support.

If the payment request should not be passed to the payment app at all without the data having been captured then we need to handle that case too.

Related: issue 97
#97

Ian

[ianbjacobs]

@adrianhopebailie,

What this suggests is that we should split out a bunch of the browser API spec into a generic mediator spec that defines the conformance criteria for a mediator. The browser API spec would then reference that document and define the specific behavior of a UA (as mediator) including the API it exposes and state changes etc.

At first glance I like the idea of a Mediator spec (written for those implementers), a payment app spec (written for those implementers), and links between them. Here's an experiment to see what it might look like to divide things up by role:

Mediator spec:

• Receiving the payment request (from the user agent)
• Computing intersection of payment methods
• Displaying choice of payment apps to user
• Invoking payment app based on user selection
• Communication between user agent and mediator

Payment app spec

• Registration, update, unregistration
• API for receiving payment request (from mediator)
• API for sending payment response (to mediator)

Ian

[adrianhopebailie]

@ianbjacobs,

Using a list of tokens means the API spec does not need to change in future for new types to be added.

I don't think I agree. If you want to change what it means to conform (by adding a new feature) you need to revise the spec.

The list of tokens should not be defined in the API spec. This allows the API shape to stay the same and for browsers to begin supporting new data types in future.

I don't believe the specific list of data that the browser can gather for you should be part of the conformance criteria. Rather we should have an elegant way for developers to discover which data the user's browser can provide and which data they must collect themselves via the website.

So 👍 to this statement:

If we take that approach, it will be (even more) important for user agents to declare programatically what features they support.

Further, if the only conformance requirement is accepting a list of identifiers then this can expand to include identifiers of a variety of types in future. My proposal uses schema.org type identifiers but it could be URLs or some other identifier in future. This also allows the user agent to hand this functionality off to another service like an identity provider in future (mentioned as being important by @AxelNennker and Joerg from DT).

[burdges]

A "way for developers to discover which data the user's browser can provide and which data they must collect themselves via the website" sounds implausible because the information can only be transfered with the payment request. And results depend upon the payment app, not the browser configurations.