Support for fine-grained request for billing information

[ianbjacobs]

Hi all,

@samuelweiler originally raised this issue on Payment Request, but it concerns Basic Card, so moving here.

Original issue:
w3c/payment-request#842

Related issue regarding payment method data other than billing address, for consideration as well when we take this on:
w3c/payment-request#97

Ian

[David-Chadwick]

In order to solve this dilemma how about the following:
i) the full shipping address is never asked for as a data item, but rather each individual element is asked for, down to the granularity of house/apartment number.
ii) the payee marks each element as optional or mandatory. One can imagine that Country would almost always be marked as mandatory in the first instance.
The GUI then asks the user to consent to filling in each field, and he/she can miss out all the optional ones.
If the payee finds that the mandatory fields are insufficient to compute the shipping costs then it has to change some of the optional fields to mandatory and ask again. This draws a balance between protocol overhead and privacy concerns. Those users who are less concerned about privacy will provide all the optional information immediately whilst those users who are more concerned might have to have a few rounds of merchant driven negotiation.
Once the shipping costs have been computed, then any further mandatory data can be requested.
In terms of user experience the GUI can keep presenting the address until the merchant is satisfied. After the user clicks 'send' the screen will either disappear or one or more optional flags will change to mandatory and the user has to add more information and click 'send' again.

[marcoscaceres]

This needs to be balanced out with existing web forms and autocomplete, which will automatically fill everything with a single user gesture. If we overburden the UI, then the API becomes worthless (when compared with form elements). So we need to strike a balance. Suggestions about what the API should display are of course welcomed. However, the primary focus should remain on the granularity of the requested and returned data... but also considering that this API has been shipping for 2 years, so whatever we do needs to be backwards compatible.

[David-Chadwick]

Autocomplete would need to be enhanced to only support mandatory fields immediately and then to add optional ones if the user indicates to do this.

[marcoscaceres]

Would that put us back in a situation where everything would be marked as required to overcome user inconvenience?

[David-Chadwick]

That would violate GDPR so be illegal in Europe.

[marcoscaceres]

That would violate GDPR so be illegal in Europe.

We have to be careful not to move outside the constraints of the API/technical discussion. Most of us can't have a meaningful discussion about GDPR because we are not lawyers.

[chaals]

We have to be careful not to move outside the constraints of the API/technical discussion. Most of us can't have a meaningful discussion about GDPR because we are not lawyers.

Obviously, we have to make sure we are not building and promoting something that breaks the law, or encouraging implementors to make something that breaks the law.

So if we don't know enough to avoid that, we had better ask some lawyers where the lines are. (It's not good enough in any country I know anything about just to say "I don't know the law, so I will do whatever makes sense to me".)

[marcoscaceres]

@chaals, it sounds like you are deliberately trying to misconstrue what I said. Please refrain from doing that. Discussing the legality of setting required on HTML form elements in the context of GDPR is outside the scope of this issue. If folks want to discuss that, please open an issue on HTML.

Please limit discussion of this issue to the issue at hand.

[chaals]

Thinking through the proposal for starting from a minimal set of required information with the rest optional, that seems like the right solution on the face of it.

In general it should be feasible to automate progressively flipping new fields to required based on the input. If there is a legal requirement in a well-known jurisdiction not to take that information otherwise, it makes a lot of sense to acknowledge that in the spec, and describe an approach to deal with it, although given that laws can change more or less any time, figuring out where to put this needs some thinking.

[chaals]

@marcoscaceres I am not at all trying to misconstrue what you said. I am trying to clarify it and the implications. I would be surprised if we disagree about the need to make this work, and the issue at hand is "how?".

[marcoscaceres]

There is some context missing at the top of this issue. I have a concrete proposal:
w3c/payment-request#842 (comment)

If there are legal concerns, we should check with a lawyer - but it seems to me that what I propose would work across jurisdictions and be backwards compatible.

[ianbjacobs]

One note as we continue this discussion, I anticipate the "data" element of the PaymentMethodData object to be the extension point that will enable us to address some of these issues.

[ianbjacobs]

Hi all, I am proposing some new language to Payment Request API both to fix some bugs and also to set the stage for work in Basic Card to address this issue
w3c/payment-request#856

[aestes]

@ianbjacobs and I spoke about this on IRC, and I had a straw-man proposal that extends @marcoscaceres's proposal to allow for progressive disclosure of address information in Basic Card.

I don't believe Basic Card currently uses PaymentDetailsUpdate.paymentMethodErrors, but you could imagine a Basic Card error that says "I need more address granularity," which the payment handler handles by re-dispatching the paymentmethodchange event with additional information (if allowed according to the redact list).

Here is how it might work:

const basicCardRequest = {
    supportedMethods: 'basic-card',
    data: {
        supportedNetworks: [...],
        requestBillingAddress: ['country'],
    },
};

const details = ...;

const request = new PaymentRequest([basicCardRequest], details);
request.onpaymentmethodchange = (event) => {
    // country is now available in event.methodDetails; all other fields redacted.
    // assume that the merchant detects the country as 'US' and would now like to request the state.
    // this call to updateWith() will result in another paymentmethodchange event with the new requested billing fields.
    event.updateWith({
        paymentMethodErrors: [{
            requestBillingAddress: ['country', 'region'],
        }],
    });
};

This assumes that Basic Card is extended to define some sort of BasicCardError data structure that allows specifying a new sequence of requested billing address fields.

It's not clear that this would require user consent for each call to updateWith(). User consent would occur when the payment button is clicked, and user agents would never reveal more than allowed by the redact list. Full shipping and billing address information would still require authorizing payment. This would simply allow merchants who opt in to start out requesting as little as possible then iteratively get more specific as needed.

Edit: Note that unlike other errors that are meant to be displayed to the user, this proposes a type of error that will be handled internally by basic-card payment handlers. Maybe we should call it something other than an 'error' to avoid confusion.

Edit 2: this could be generalized for all payment methods in PaymentRequest itself by adding the requestBillingAddress property to PaymentOptions and adding the new error to PaymentDetailsUpdate.

[marcoscaceres]

this could be generalized for all payment methods in PaymentRequest itself by adding the requestBillingAddress property to PaymentOptions and adding the new error to PaymentDetailsUpdate.

This is my preference, tbh (w3c/payment-request#842 (comment)). I really dislike the duplication.

[adrianhopebailie]

NB: This relates to Billing Address NOT Shipping Address so let's keep the scope limited to that.

This is a critical aspect of the discussion because Billing Address is dealt with at the level of Payment Methods whereas Shipping Address is a function of the core PR API.

As it stands, Billing Address is only defined in the Basic Card payment method specification.

However, what we have observed is that the need to get a Billing Address is a common requirement (it's used in Google Pay and ApplePay for example) so we should consider carefully how this could be incorporated into the core PR API and design this properly for v1.1.

Another thing we have observed is that a Billing Address is always tied to a payment instrument (irrespective of payment method) so it makes sense for this data collection to be something that is only possible after the user has selected a payment instrument.

NB: The user may not yet have selected a payment instrument when they select a payment handler. It's possible that they still need to select a payment instrument AFTER selecting a payment handler before the browser can accurately reflect that a specific payment method has been selected.

I.e. the general flow embodied by the specs is as follows, with possible optimisations in specific scenarios:

1. Merchant requests payment and specifies accepted methods.
2. Browsers calculates the intersection of methods requested and methods supported by registered handlers
3. Browser prompts the user to select a handler
4. User selects a handler which is invoked
5. User selects an instrument
6. The browser notifies the website that the method has changed (raises the onPaymentMethodChanged event).

Note: The merchant, at this point, only knows which method the user has selected not details about the handler or instrument.

Note: With Basic Card the UX is slightly different. The browser presents the user with instruments to select so as soon as these are selected we go straight to 6.

I recap this to indicate that we should look at updating the design of the onPaymentMethodChange event to be more aware of these distinctions and not simply update Basic Card which is somewhat exceptional.

Currently @aestes proposal and the way that GooglePay interacts with the website regarding Billing Address (if I recall how @rsolomakhin explained it to me) is a bit of a "hack" to get around the fact that Billing Address is hidden behind payment methods which have no common standard for the data they require or return.

So concretely, I propose that we look at updating the PaymentMethodChanged event to include methods that allow for the interactions/negotiation suggested by the Privacy IG review.

Something like this:

const basicCardRequest = {
    supportedMethods: 'basic-card',
    data: {
        supportedNetworks: [...],
    },
};

const details = ...;

const request = new PaymentRequest([basicCardRequest], details);
request.onpaymentmethodchange = async (event) => {
    const [country] = await event.requestBillingAddress(["country"])
    // assume that the merchant detects the country as 'US' and would now like to request the state.
    const [state] = await event.requestBillingAddress(["region"])
};

This would be a significant change to the API so I suggest we aim to do this in v1.1 and for now we accept that the proposed changes to Basic Card may be sufficient.

[marcoscaceres]

@adrianhopebailie wrote:

This is a critical aspect of the discussion because Billing Address is dealt with at the level of Payment Methods whereas Shipping Address is a function of the core PR API.

You are correct - though PaymentOptions.requestBillingAddress is in Payment Request. Basic Card pivots back into Payment Request to actually gather the billing address (Steps 3.2 of "steps for when a user changes payment method").

As it stands, Billing Address is only defined in the Basic Card payment method specification.

You are correct. However, the only reason that it's only in Basic Card is that we have only defined one standardized Payment Handler (Basic Card). In my mind, there are some central questions relating to PaymentOptions.requestBillingAddress in Payment Request that we need to sort out.

So, before we talk solutions, let's make sure we have agreement on the invariants relating to requesting billing. I'll frame these as questions as we need to get to yes/no answers to then proceed to a solution:

1. Must every payment instruments of a payment handler have a billing address?

2. Given N payment handlers, is there a case where it's possible for one payment handler to return a billing address, but for another payment handler not to return a billing address?

For example. Given [Apple Pay, Basic-Card, ...arbitrary-payment-handlers], and requestBillingAddress: true, could any of those not return a billing address?

2. Given N payment handlers, is there are a case where the requested billing address would require a different specificity per payment handler?

For example. Given [Apple Pay, Basic-Card, ...arbitrary-payment-handlers], and requestBillingAddress: true, would it ever make sense to ask?:

• Apple Pay: I ONLY need the country and the post code.
• Google Pay: I need the country, the city, and the post code.
• Arbitrary-payment-handler: I need the country, the city, the post code, and the region Code.

[ianbjacobs]

Hi @marcoscaceres,

Must every payment instruments of a payment handler have a billing address?

I have heard people say that Bitcoin does not require a billing address.

Given N payment handlers, is there a case where it's possible for one payment handler to return a billing address, but for another payment handler not to return a billing address?

If it's true that Bitcoin does not require a billing address, and if the merchant accepts basic card and bitcoin, then yes.

Given N payment handlers, is there a case where the requested billing address would require a different specificity per payment handler?

I don't know.

[marcoscaceres]

I have heard people say that Bitcoin does not require a billing address.

I’m not sure it’s up to the coin, but the jurisdiction? Like, how would one calculate taxes like VAT without the billing address?

[ianbjacobs]

Tracking several threads related to this:

• Enhancing requestBillingAddress to allow for an array
  Richer negotiation re: address redaction? payment-request#842 (comment)

• Passing that array to the payment handler
  Support delegating collection of shipping address and other user data to Payment Handler payment-handler#337 (comment)

• At which point we would modify the "Steps for when a user changes payment method " so that
  the payment handler only includes billing address information that is requested AND that is not
  in the redactList.

[marcoscaceres]

Scribbled some ideas w3c/payment-request#866

[ianbjacobs]

Here's another idea: Payment Request API supports "requestPayerPhone". We have been talking about Payment Handlers being delegated flags (see [1]). One way to handle returning phone with the billingAddress is only if requestPayerPhone is true. That would be in addition to any user agent config option to allow the user not to store or return the phone.
Ian

[1] w3c/payment-handler#337

[marcoscaceres]

Could we split this discussion into two pull requests? We had consensus on earlier redact list... we an at least land that and then continue discussing billing phone.

[joshkaroly]

I’m in for these changes for shipping addresses, but please extend to billing address as well.  As a merchant you can send through different variations of the address for verification, including not sending at all. (Full address, zip only, zip+4, etc.) We for example, only use the 5 digit zip in the US.

[marcoscaceres]

Spec was deprecated. No longer applies.