Support delegating collection of shipping address and other user data to Payment Handler

[danyao]

Today if a merchant requests shipping address or payer's contact information, the data collection is always handled by the browser. At last week's WPWG FTF in Foster City, there was interest among payment providers to be able to provide this information. Supporting this delegation can lead to better user experience because the payment app may have more accurate information than the browser.

We should support delegation for all fields that are currently requested via PaymentOptions: https://w3c.github.io/payment-request/#dom-paymentoptions

[rsolomakhin]

A payment handler should specify their own capabilities.

registration.paymentManager.capabilities.set(
    ['requestShipping', 'requestPayerEmail'])
  .then(handleDoneSettingCapabilities)
  .catch(handleError);

This will allow user agents to re-use the keys of the PaymentOptions dictionary.

The PaymentRequestEvent should include readonly booleans for these options.

self.addEventListener('paymentrequest', evt => {
  if (evt.requestShipping) {
    doSomethingForShippingAddresses();
  }
});

A payment handler should also be able to fire the relevant events for the merchants.

registration.paymentManager.fireEvent(
    paymentRequestIdentifier, 'shippingaddresschange', {country: 'CA'})
  .then(handleUpdateWith)
  .catch(handleError);

User agents can reuse event names from Payment Request, such as shippingaddresschange.

The event firing method should be on the paymentManager object and keyed by the payment request identifier for ease of access by the payment handler window, where the user would be interacting with their shipping addresses and contact information. This is the pattern that we plan to use for responding to paymentrequest events in the future as well, so that the service worker process does not have to stay alive while the payment handler window is interactive.

[rsolomakhin]

Passing the paymentRequestIdentifier into the fireEvent() method might confuse web developers into thinking that they can handle arbitrary Payment Requests, even those not going through their service worker. Let's provide the web developer with a context for the current payment in a self-contained object.

registration.paymentManager.paymentRequestEvent
.then((evt) => {
  console.log('Firing the method change event for payment request ' +
      evt.paymentRequestId);
  evt.changePaymentMethod('https://bobpay.xyz', {billingAddress: {country: 'CA'}})
  .then(handleUpdateWith)
  .catch(handleError);
}).catch(handleError);

The paymentRequestEvent promise would be resolved only in the window that was opened via PaymentRequestEvent.openWindow() in the service worker.

@romandev : This is similar to your idea of delegating the full payment lifecycle to the payment handler window, right? This would allow the payment handler window to respond to the Payment Request without looping back into the service worker:

registration.paymentManager.paymentRequestEvent
.then((evt) => {
  console.log('Responding to payment request ' +
      evt.paymentRequestId);
  evt.respondWith({methodName: 'https://bobpay.xyz', details: {token: '123'}});
}).catch(handleError);

This design still allows for UI-less payment handler, which might be necessary for some use cases.

[ianbjacobs]

@danyao and @rsolomakhin,

I am rereading this issue in light of this Basic Card issue:
w3c/payment-method-basic-card#72

Suppose we were to make changes to Payment Request as @marcoscaceres suggested:
w3c/payment-request#842 (comment)

In order for a payment handler (e.g., a third party payment handler doing Basic Card, but also any third party payment handler for any payment method) to know which fields of the response data to return (or not), we need to pass the array to the payment handler.

Thus, I think we should prepare for the mediator to hand "request*" to the payment handler, whether a mere boolean or an array.

Make sense?

Ian

[rsolomakhin]

@ianbjacobs : Yep, it makes sense to pass such booleans as "requestShipping", "requestPayerEmail", "requestPayerName", and "requestPayerPhone" to a payment handler. Is that what you had in mind?

[ianbjacobs]

@rsolomakhin, yes, that's what I have in mind. In some cases they will be booleans (e.g., requestPayerEmail) but there's a chance we might also start using arrays (e.g., for requestBillingAddress)...we aren't yet but if we do I want to be sure PH API can handle that.

[rsolomakhin]

I don't see any blockers here, so go ahead :-D

[ianbjacobs]

See related pull request in PR API:
w3c/payment-request#866

[tblachowicz]

Delegation of data collection, as described above, would be particularly useful for SRC Payment Method we've been working on. Apart from payment credentials, In SRC the following data can be provided to the merchant on request:

• shipping address
• billing address
• consumer contact detail: name, e-mail address and phone number.

Furthermore, the model for requesting the specific data element is largely in line with PR API.

[tblachowicz]

I wonder if the proposed API would allow the browser to pull addresses and contact details from registered Payment Handlers to present combined data as part of payment sheet experience to the user for selection?

Alternatively, the API could allow delegation of a user to dedicated UX of Payment Handler to complete the selection of data addresses and other requested data elements. That approach would require address selection to be deferred after the payment instrument is selected so it's known which PH to delegate the user to.

[rsolomakhin]

@tblachowicz : My thinking is along the lines of delegating the full payment flow to your payment handler, if you're able to provide all of the requested data. The browser's sheet will be skipped, similar to the current Google Pay implementation.

[tblachowicz]

@rsolomakhin: In case there is more than single capable payment handler installed in the browser the appearance of the payment sheet in some shape or form is unavoidable. The consumer must be able to select the desired payment instrument e.g. SRC or Google Pay.

In general, skipping the browser's sheet sounds like a great idea, but it's limited to the case where there is only single PH installed or Merchant requests a single specific payment method. Am I getting it right?

[rsolomakhin]

@tblachowicz : That's right. In addition, it would be great to introduce a user setting for a default payment handler (per merchant origin, for example), so the sheet can be skipped more often.

[tblachowicz]

@rsolomakhin: I was wondering whether end user should be able to select preferred/default payment handler e.g. wallet or preferred/default payment instrument e.g. specific card with the wallet.

[rsolomakhin]

@tblachowicz : Yep, I think the end user should be able to select preferred/default payment handler.

We are trying to stay out of what happens inside of the wallet, so it would be up to the wallet provider to let the end user select the default instrument within the wallet. Payment apps already do this today, AFAIK.

[tblachowicz]

(I deleted that comment unintentionally yesterday, posting again)

@rsolomakhin : OK. I understand your point. Would you consider embedded Payment Handler e.g. an implementation of the basic card also as a wallet?

I've just double checked the current version of the specification to compare the approaches. In the initial section 2. Overview of Handling Payment Requests there is a description of the flow that assumes that payment handler sets a list of payment instruments, such as individual cards, that are used by the user-agent to facilitate selection of payment credentials by the consumer. I understand the flow that the payment instrument is presented to the end-user by the browser, not the wallet or payment handler. I wonder if my reading of the specification is in line with the intent of the authors and the interpretation of others.

[rsolomakhin]

@tblachowicz wrote:

Would you consider embedded Payment Handler e.g. an implementation of the basic card also as a wallet?

Yes, that's an autofill wallet.

I understand the flow that the payment instrument is presented to the end-user by the browser, not the wallet or payment handler.

The spec allows for this, but does not require it. We wanted to keep the API consistent for both use cases, while giving the browser implementers some freedom to experiment with actual UI. Exposing individual instruments from payment handlers is not high on our priority list, although we have heard calls for it from the industry, so it's not out of the question entirely.

[tblachowicz]

While I believe it's an important discussion to have I think we've diverged from the main topic that'd been the delegation of collection of shipping, billing and contact details from the end-user. I suggest we get back to the topic here. If there is any other thread related to the subject of wallet vs payment instrument I'm happy to jump there.

[ianbjacobs]

@tblachowicz,

Today the Payment Handler API supports instrument level presentation and selection by the user:

• For presentation, each instrument includes information (provided at registration) about name and icons [1]
• For information about which instrument the user selected, the browser can pass the instrumentKey [2] to the payment handler.

We don't have any implementations today of the latter feature (that I'm aware of).

I don't think we have any open issue on this topic because it is already in the specification. I think shedding light on the importance of these features for various payment methods is a good way to restart the conversation. If you think there are additional specific features needed to address the desired capability, I encourage you to raise new issues.

Thanks for weighing in!

Ian

[1] https://w3c.github.io/payment-handler/#paymentinstrument-dictionary
[2] https://w3c.github.io/payment-handler/#instrumentkey-attribute

[tblachowicz]

Thanks for clarifications @ianbjacobs.

[sahel-sh]

Chrome is proposing changes to Payment Handler API to enable shipping and contact info delegation. Please see the WIP Explainer below:
https://github.com/sahel-sh/shipping-contact-delegation/blob/master/Explainer.md

[sahel-sh]

The Explainer has been updated with JIT installation, and skip the sheet:
https://github.com/sahel-sh/shipping-contact-delegation/blob/master/Explainer.md