Change the way we request user data

[zkoch]

This is a proposal to:

1. Change the way we request user data. It's now an array with a known set of strings that are supported. A similar model is followed by the permissions api.
2. Add support for the collection of phone and email. Email because it is used by the merchant to email a receipt of the transaction and phone because it is often required by shipping providers.

Note that the addition of phone and email doesn't also mean the addition of new event listeners. There are no implications to an email or phone that would require the merchant know these before the payment request is returned.

[msporny]

I don't think we had consensus to support collection of email address at the face-to-face.

[zkoch]

Correct, this is a proposal to include the collection of email and phone as part of the API.

[msporny]

Ok, I'm used to this sort of stuff being hashed out in an issue before there is a PR. Not sure what this group's process is...

[ianbjacobs]

There was support at the FTF meeting to draw merchant attention to this issue via a Note. Personally I have no objection to drawing merchant attention via a Note to the concrete proposal.

Ian

[adrianhopebailie]

I think it's premature to put this in the spec.

I'd recommend a note is added that suggests we are looking for input from the community on whether we should be gathering any data other than shipping address and based on that a PR that reflects the consensus of the group on this issue.

[mattsaxon]

We are going to need the ability to capture email addresses and phone numbers for various payment methods, the question for me if how we do this in adequately secure and private manner. If we continue to treat the Payment Application as just a dumb form filler this is going to get messy, I propose we spend more time on completing the payment application parts and adding security features to the existing API before extending the scope of what data can be collected.

[webpayments-specs]

+1 to mattsaxon's concept

On Sun, Mar 20, 2016 at 10:24 AM, mattsaxon notifications@github.com
wrote:

We are going to need the ability to capture email addresses and phone
numbers for various payment methods, the question for me if how we do this
in adequately secure and private manner. If we continue to treat the
Payment Application as just a dumb form filler this is going to get messy,
I propose we spend more time on completing the payment application parts
and adding security features to the existing API before extending the scope
of what data can be collected.

—
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub
#65 (comment)

-Shane

[adrianhopebailie]

@zkoch can you edit this PR to be an issue marker (as opposed to a spec text change) indicating that the group is intending to discuss if email and phone should be included in this API and is seeking input from the community?

[burdges]

I generally believe merchants should do whatever data collection they need before invoking the payment method. It's opening a big can of worms if the payment method deals with this : Is the user agent being clear enough about what user data it reveals? If not, that'll violate laws various places. Is/should the merchant actually see the data or just the PSP? etc.

There is obviously an advantage to the payment app being able to communicate data to the PSP without communicating to the merchant, as this reduces the merchant's EU DPD compliance burden, but that exists regardless, and is payment app specific.

[zkoch]

I'll create a new PR and keep this one as-is, as I prefer the enum style as opposed to boolean in a dictionary. That said, I'm happy for this PR to linger until a decision is made.

[kirkalx]

Line 1118 should probably change from
is <code>true</code>, then if the <code>shippingAddress</code> attribute of <em>request</em>
to
then if the <code>shippingAddress</code> attribute of <em>request</em>
or something like that...

[adrianhopebailie]

@burdges to be clear this would not affect the payment method at all.

This data collection capability is a facility that the user agent offers to streamline the flow because browsers often have this data and can present a standard UI to the user if not (and then will have it the next time).

The data is returned directly to the website (not passed to the payment app) via events that fire before the payment request is passed to the payment app.

[adrianba]

I'm not in favour of the design of this pull request because I'm not convinced that all the values we will request will be Boolean.

For example, I think it is reasonable to have requestEmail be required or optional. Some merchants absolutely require an email address and won't let you checkout without providing one. Others give you the option to provide an email address only if you want them to send you a confirmation, etc.

For phone number I think it is important that we can differentiate between requesting the payer's phone number, which might be used for billing enquiries, from the recipient's phone number, which might be used for shipping enquiries. In each of these cases, the field might be required or optional.

[adrianhopebailie]

Also note the significant discussion on #1 including comments from TAG review by @triblondon

There seems to be consensus that the tokenized approach is preferred however we need to accommodate @adrianba 's requirement for more granularity in the request (i.e. is this data mandatory or optional)

@zkoch perhaps this could be updated to use the Descriptor pattern in the same vein as the Permissions API to accommodate @adrianba 's requirement?

Something like:

dictionary DataDescriptor {
  required DOMString name;
  required boolean optional = false;
};

dictionary ShippingAddressDataDescriptor : DataDescriptor {
  sequence<ShippingOption> shippingOptions = false;
};

dictionary PaymentOptions {
  sequence<DataDescriptor> requestData;
  ...
};

Two things to note from the discussion on #1:

1. the arguments against explicitly listing the set of data that can be requested.
2. the arguments for a fluid API for setting these requirements which looks like it will be a lot more developer friendly if this list grows (see also Should the payment API be more conversational or less conversational? #51).

[adrianba]

One problem with this is that it seems to constrain us now to only Boolean values that can be optional. What if we want an option that can be an enum with multiple options.

Also, passing

{ request: [{name: "shippingAddress"}, {name: "email",optional:true}, {name: "phone-number",optional:true}] }

seems a lot less friendly than

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

The latter seems less complex and is more flexible.

[adrianhopebailie]

One problem with this is that it seems to constrain us now to only Boolean values that can be optional. What if we want an option that can be an enum with multiple options.

Making that member boolean is just a proposal, it could be a string or an enum.

#145 makes the case for this being a lot more flexible than the current spec allows.

[adrianhopebailie]

{ request: [{name: "shippingAddress"}, {name: "email",optional:true}, {name: "phone-number",optional:true}] }

seems a lot less friendly than

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

The latter seems less complex and is more flexible.

Less complex but with no extensibility for websites to request other data types or for browsers to support these without a revision to the spec.

If it suddenly becomes very common to collect some new piece of data as part of a checkout process (like social security number or website URL) websites have to collect this as part of a separate flow until browsers catch up and start supporting them.

[adrianba]

Less complex but with no extensibility for websites to request other data types or for browsers to support these without a revision to the spec.

Whether you change an enum or add a field you have to change the spec. Or write an extension spec. This is a feature not a bug - it is necessary for interoperability should it become "very common to collect some new piece of data as part of a checkout process".

[adrianhopebailie]

@adrianba said:

Whether you change an enum or add a field you have to change the spec. Or write an extension spec. This is a feature not a bug - it is necessary for interoperability should it become "very common to collect some new piece of data as part of a checkout process".

In issue #145 Shopify have surfaced another very real requirement that I believe would prevent them from using this API if it was not supported. Note comment from @andrewpaliga:

we have experienced better cart conversation rates by making the option [of collecting giftcard or coupon codes] available throughout our checkout experience.

This suggest to me that a minor change to my proposal would solve this issue:

enum DataType {
  "date",
  "number",
  "address",
  "email",
  "telephone",
  "url"
  "string",
  ...
};

dictionary DataDescriptor {
  required DOMString label;
  required DataType type;
  required boolean optional = false;
};

dictionary ShippingAddressDataDescriptor : DataDescriptor {
  sequence<ShippingOption> shippingOptions = false;
};

dictionary PaymentOptions {
  sequence<DataDescriptor> requestData;
  ...
};

Example website code:

{
  requestData: [
    {
      label: "Shipping Address",
      type: "address",
      shippingOptions: [...]
    }, 
    {
      label: "Email Address",
      type: "email",
      optional: true
    }, 
    {
      label: "Voucher Code",
      type: "string",
      optional: true
    }
  ] 
}

It would be very unlikely that we would ever need to change the DataType enum as this is simply a way of hinting to the UA what input control(s) to use and for any new data requirement merchants could simply use the string or number data type.

[adrianba]

My understanding was that Zach was proposing a mechanism to indicate to the user agent that the page wanted to request email and phone number. This was modeled on the Permissions API, which also has a concrete list of allowed data.

One problem I have with Zach's proposal is that, compared to the Permissions API where you are either asking for a permission or you are not, we might have situations is which collecting a value is desirable but not required.

As I understand it now, @adrianhopebailie's most recent proposal is trying to turn this into a general purpose "gather any kind of data" proposal. I do not support this.

I support the idea that the web page should be able to ask for specific data with known semantics such as, in Zach's proposal, email and phone number. This allows the user agent to provide an informed user experience that can make it clear to the user what data they are sharing. It also allows us to offer data that we already know about the user (such as their email address or phone number). I don't want to try to build a user experience for the collection of arbitrary data with unknown semantics.

[rsolomakhin]

IMHO, the page should request the minimum amount of information necessary to process the transaction. If email address and phone number are desirable, but not required, this information should not be requested. @adrianba Did I miss a use case that you had in mind?

[webpayments-specs]

I agree with this statement. What is necessary should be gathered for payment to not allow the process. The rest should be left to e-commerce applications.

David Jackson | Senior Director Financial Services
M: +1.614.560.1237 | VoIP: +1.614.465.6654
Oracle Industry Solutions Group
New York City | Columbus

Rouslan Solomakhin notifications@github.com wrote:

IMHO, the page should request the minimum amount of information necessary to process the transaction. If email address and phone number are desirable, but not required, this information should not be requested. @adrianba Did I miss a use case that you had in mind?

—
You are receiving this because you commented.
Reply to this email directly or view it on GitHub

[adrianba]

Did I miss a use case that you had in mind?

Yes, I think I mentioned above sites that optionally allow you to receive a receipt. I'd prefer that we enable sites to continue this practice rather than giving them the choice to require it or not offer that service (since they might shift to requiring it). It's not mandatory for v1 to support this but I don't want us to design the API in such a way that we can't do this.

[rsolomakhin]

👍

[jnormore]

To @adrianhopebailie's dynamic data collection proposal, we would strongly support this, as he mentioned it would prevent us from using any solution to it's full potential without it due to the discount code issue. To expand on that, we have a platform of merchants who all have different data preferences or requirements for their customers to purchase something, VAT ID is another one that is common for B2B merchants and affects tax amount in a very dynamic way, this is not a payment app concern, it is between the merchant and their customer.

All of this could be collected before initiating the payment request but that defeats the purpose of streamlining the checkout flow in order to reduce cart abandonment rates, as soon as you add another step to the checkout process (another decision for the customer to make, to continue or not) abandonment increases, not to mention the fragmented look and feel of the checkout experience with the merchant handling some while the user agent is handling the rest. There's also scenario of a single product page buy button, where there is no cart yet but the customer can save time by just hitting "Buy Now" while viewing the product details, the faster you can get the customer into the user agents checkout experience the better, jumping to another merchant hosted page just to ask for a discount code would be a bad experience for the customer.

[adrianba]

All of this could be collected before initiating the payment request but that defeats the purpose of streamlining the checkout flow in order to reduce cart abandonment rates...

There will be no streamlining if you just present a list of arbitrary data fields. You might as well use a HTML form at that point. Only by applying semantic meaning to the data fields can the user agent be smart about how to populate them.

[adrianhopebailie]

@adrianba said:

There will be no streamlining if you just present a list of arbitrary data fields. You might as well use a HTML form at that point. Only by applying semantic meaning to the data fields can the user agent be smart about how to populate them.

Browsers do a pretty good job of this with form autocompletes today. I'd argue that the more granular data types (like email, address, phone number) will make this even easier.

An alternative to solving this is to have a requestGiftCardOrCouponNumber member as an addition? But then I wonder what we would label this as it is probably different from merchant to merchant.

The motivation for allowing this data collection directly by the user agent was originally for shipping address as it was argued that this could significantly streamline the checkout because almost all onine purchases include shipping. Now there is an argument to add email address and phone number and also define additional semantics about whether this data is required or optional but we are hearing directly from a company that services thousands of merchants:

who all have different data preferences or requirements for their customers to purchase something

that trying to enumerate the set of data the user agent can collect is not going to work.

So where do we draw the line and based on what logic?

[ianbjacobs]

@jnormore,

I am glad to hear of the discount code use case; that reinforces my sense (in discussion
within the web payments IG) that loyalty, coupons, discount codes, etc. would be a valuable layer
on top of the infrastructure we are building.

I believe, however, that those are out of scope for our current working group per our charter [1]: "Recommendations for loyalty schemes and coupons, digital receipts, digital credentials, tickets, and location services are out of scope. Future W3C activities may seek to increase interoperability of these or other additional digital wallet capabilities."

I am still interested in finding ways to create a superior user experience based on merchant/customer
dialog, and what guidance we might provide to any merchant that wants to use the (future) API
but where the API does not have built-in features to let them collect data that they need. Should this happen before pushing the buy button? Should payment apps step in through back-channel discussions with merchants and offer their own UI for gathering data?

Ian

[1] https://www.w3.org/Payments/WG/charter-201510.html

[adrianhopebailie]

@ianbjacobs I see the use case from Shopify as an indication of the need for us to not try to specify what data can be collected through this API irrespective of whether or not the use case itself is out of scope.

I hear concern from @adrianba about defining a generic data capture API but have my own concerns that we are committing a cardinal design sin by assuming we know more than we do about what is required based on our own limited knowledge of how our API will be used. What's more, we are doing this even though it is being demonstrated to us that we are already wrong before we have even left the drawing board.

[adrianba]

we are committing a cardinal design sin by assuming we know more than we do about what is required based on our own limited knowledge of how our API will be used.

I don't think that is true - on the contrary, I'm trying to start small and iterate (this was my first comment to the group at TPAC). We should recognise that v1 of the API won't address all use cases one can imagine but we need to start with something we can implement in a reasonable timeframe, experiment, iterate, and then improve and expand.

In the end, on a case by case basis, for v1 people will choose to:

1. Use the API because of its advantages despite some disadvantages
2. Use the API but provide additional data gathering for things the API doesn't yet support
3. Avoid the API until it provides needed functionality.

Finding out what people need in (2) and (3) will help us focus on what to do first in v2.

I expect to have a proposal for email and phone collection either today or tomorrow pending internal feedback.

[dlongley]

@adrianba,

I don't think that is true - on the contrary, I'm trying to start small and iterate (this was my first comment to the group at TPAC).

Starting small and iterating is still picking a particular mechanism by which to collect the information. I don't think that the problem is necessarily with what we collect (though this has influence), it is the mechanism by which we go about doing it. In order to collect anything at all, we have to pick some mechanism to go with -- and choosing this too early is what is being cautioned against.

If "iterate" means that we may completely change the mechanism by which we collect the information (and phase out support for the old, flawed way) that's one thing. If "iterate" just means that we'll consider adding more items to be collected using the same mechanism in the future, I think that's too limited -- and we'll be locking ourselves into something we may not want at all.

[nickjshearer]

+1 to @adrianba's comments

[jnormore]

I think there may be a middle ground here that doesn't force UAs to implement a dynamic UI that could become overly complex (in the user experience) because of dynamic inputs that could very well be completely optional (discount, VAT ID, etc), but still give the merchant the ability to request information that is required like email or phone.

I propose that we could stay away from generic / dynamic inputs for the required fields and expand on requestEmail, requestPhone, etc for these, this will give UAs the flexibility to implement the best UI possible. But for optional data we allow a generic definition like the spec AdrianHB proposed, this could be in the form of something like additionalInfo that the UA doesn't have to make a primary part of the checkout flow but should make accessible in some secondary way (button/link that displays the generic inputs, could allow customizable label on this, for example "Additional Info" or if it's just a discount code it could be "Have a discount code?"). Please excuse the stream of text here, I believe @andrewpaliga was going to submit a more formal or polished proposal for this at some point.

[adrianhopebailie]

An interesting consideration here is when, if ever, we pass these data requests on to a third-party app like the payment app. In some cases this complicates things because the data is used to calculate the price but I'd expect data like email to be something a user's payment app would be readily able to provide.

I can understand @adrianba 's logic about keeping simple and iterating but I am concerned that our ability to change the shape of the API in the future is limited and where we set the bar in terms of number of data points before we change how this is done.

At what point do we say we need to change? Is it when there are 5 different data points to request or 10 or never?

When do we decide that this is working or not and how do we decide that? Who will have the data to back up an assertion either way.

Finally, I'd be very interested to hear if there is a way we could A/B test this

[adrianhopebailie]

@jnormore and @andrewpaliga it would be great to see proposal for this that we can consider on the call next week

[andrewpaliga]

Proposal for capturing optional data for the payee:

1. Add section to the payment request to request "additional info" option be displayed by the user agent.
2. "Additional info" (or a custom label) option/button is displayed by the user agent.
3. When the payer presses "Additional info" (“Add VAT Identifier” in example) the user agent renders a separate view to collect the information based on the request data specified by the payee (similar format to dynamic input field proposed by Adrian).
4. Payer fills out field(s) and submits form and the data is sent to the payee.

Ex. “Add VAT Identifier" placement within user agent

Ex. Request data provided by payee

{
  requestData: [
    {
      label: "VAT Identifier",
      type: "string"
    }
  ] 
}

Considerations

• “Additional info” data would be expected to outside of the primary checkout flow, it would exist on a secondary view that doesn’t interfere with the streamlined checkout flow offered by the UA.
• This approach is meant to limit the impact additional info requirements would have on checkout experience while still providing flexibility.
• All info captured in this form would be optional.

[adrianba]

Fixed by #174.