I've heard feedback from payment app writers that merchants need a way to suggest payment apps to the user. Let's specify how this happens, exactly. Here's a few options.

If the merchant specifies a payment app identifier URL for which no payment app has been installed, then the user agent SHOULD display this URL to the user as a "suggested app." A payment app identifier URL is a ServiceWorker URL, e.g., https://bobpay.com/payment-app/, which SHOULD also have an index.html that lets user register the payment app. If the user selects the suggested app URL, then the user agent SHOULD open the URL and wait for the payment app to register itself. (User can interact with the webpage at this point to, for example, enter their credentials.) Once the payment app is installed, user agent SHOULD fire the PaymentRequest event in this payment app with the information provided by the merchant.

Does this sound any good? If so, let's spec something out.

Some ways to improve with pros and cons:

• Payment app identifier URL should be the location of the JS service worker of the payment app, e.g., https://bobpay.com/payment-app/app.js.
  • Pro: No need to open the webpage to install the service worker.
  • Con: The service worker needs to open a webpage anyway to get user credentials after it's been installed.
  • Con: Presenting something.js file in the UI to the user is ugly.
• Merchant website should provide a human-readable name and an icon URL for the suggested payment app.
  • Pro: No need to show https://bobpay.com/payment-app/ to the user.
  • Con: Burden on the merchant.
• User agent should retrieve the favicon and the title of the page at https://bobpay.com/payment-app/ and show that in its own UI.
  • Pro: No need to show https://bobpay.com/payment-app/ to the user.
  • Con: User agents pings https://bobpay.com/payment-app/index.html and https://bobpay.com/favicon.ico every time the merchant suggests a payment app that's not installed.
    • https://bobpay.com may get overloaded.
    • https://bobpay.com learns about the user's IP without user's explicit consent.

@rsolomakhin,

This sounds like the same intent of the "Recommended payment apps" described in the spec. Thank you for digging down into the next level of detail. Can we agree to call them "recommended payment apps" instead of "suggested payment apps" simply because the former term has been used for a longer period of time?

Some notes:

• Yes, we need payment app identifiers. Those identifiers will allow the browser, for example, to determine whether a recommended payment app has already been installed and is ready to make payments, in which case, the browser can enable user configuration (for example) to "show recommended payment apps that are enabled" at the top of the list. (That's just an example.)
• We have talked in the past about recommended payment apps being "ready to use without requiring registration". Registration should not be required to use the app for the current transaction, but is important for persistent use. Therefore, I agree with "SHOULD " have a payment app manifest. And also the user agent MAY offer the user the opportunity to register the payment app. (or that may happen automatically on configuration, as in "Whenever I choose to pay with a recommended payment app, automatically register it for me for future use."
• You wrote "Once the payment app is installed." I am using terms this way: registration means "provide metadata to the browser" and installation means "install a piece of software in the operating system." So, for native payment apps, installation may be necessary. (And installation may lead to registration, if the operating system determines that software installation is one way to register a payment app so that the browser learns about it through some OS mechanism.) But for Web-based payment apps, no registration (of the payment app with the browser) should be necessary for the current transaction.
  (Please note here that I am NOT talking about whether the user must create an account with a payment app; that's a different kind of enrollment.)

Let me start there and see if those points resonate with. I'll put this on Wednesday's agenda.

Ian

Agree 100% with everything you said, @ianbjacobs.

Hi all,

Here is a summary of our discussion about Recommended payment apps
from the 4 January 2017 call [1]:

• Rouslan and Jason indicated that discussions with payment app
  providers suggest this is an important feature. Merchants
  and payment app providers are likely to have agreements in
  place about the use of names and logos. There was consensus on the
  call that it is desirable for merchants to be able to provide
  name and icon information about recommended payments to the
  browser.

• To help with the conversation we tried to disambiguate some terms.

  REGISTRATION: Registering a service-worker with the browser; this
  service worker is how we manage the payment app
  life cycle. Registration provides the browser
  with access to a Payment App Manifest, which
  includes information such as names, icons, etc.

  ENROLLMENT: This relates to the user's relationship with the
  payment service provider, such as "getting an account"
  with some provider. Enrollment is outside the scope
  of this specification.

• When the user agent displays a registered payment app, it uses
  name/icon information from the payment manifest. This information
  is not available in the case of unregistered recommended payment
  apps. There was consensus on the call that the merchant should
  therefore provide (through the API) enough information to

  1. identify the service worker for the payment app, and
  2. display an icon and label for the payment app

• It was noted that in some cases, the merchant may recommend a
  payment app that the user has already registered. There was
  consensus on the call that the merchant should be able to
  COMPLEMENT label/icon information provided via the payment app
  manifest, but not override it. This would likely confuse the
  user, for example.

  We did not have time on the call to flesh out ideas for how
  merchant-provided information (e.g., "Use bobpay for a 10%
  discount") could be displayed alongside payment app
  manifest-provided labels and icons. One idea mentioned is to
  display the app twice: once in the "registered" area and once in
  the "recommended" area. We need to discuss this topic further.

• There seemed to be agreement to view the recommended payment
  app flow as follows:

  • The merchant may identify one or more recommended payment
    apps, providing label(s), icon(s), and identifying the
    Web-based payment app service worker.

  • If the user has already registered a payment app, the
    browser MAY use this information to display this payment
    app specially.

  • If the user has not yet registered a payment app,
    then the merchant-provided information is used to display
    it as selectable by the user for this transaction.

  • If the user selects an unregistered recommended payment
    app, it is first registered. Processing at that point is
    the same as when the user selects any registered payment
    app.

  In other words: Recommended payment apps behave just like
  registered payment apps once they have been selected.

• One implication of this discussion is that we are going to need
  to modify an existing statement in the specification [2]:

  "Registration is not a prerequisite for using a payment app. In
  particular, a user should be able to pay with a
  merchant-recommended payment app that the user has not yet
  registered."

  The conclusion of today's discussion was that, for Web-based
  payment apps implemented as service workers, registration is
  required before usage. The statement may still be true for native
  payment apps, but we do not plan to address them in detail in this
  specification.

I expect to make some edits to the spec based on this summary.

[1] https://www.w3.org/2017/01/04-apps-minutes.html#item06
[2] https://w3c.github.io/webpayments-payment-apps-api/#registration-and-unregistration

In light of recent discussions including on 7 February [1], I propose that we:

• Remove recommended payment apps from the payment app API.
• Continue to work on recommended payment apps in the payment app task force, either looking for good practice (e.g., the merchant can react to a rejection of the promise returned from show()) or some other approach to recommendations outside of the communication between browser and payment app (for example, through some declarative means outside the API; I think AdrianHB mentioned he could explore the use of HTTP Link headers).

This will let us move the spec forward and continue to discuss a recommendation "layer" independently (as Marcos also suggests [2]).

Ian
[1] https://www.w3.org/2017/02/07-apps-minutes#item03
[2] w3c#48 (comment)

I have experimented a bit with how to do Payment App recommendations outside of the Payment Request API. You can try out my approach by first installing an Android client with support for Payment Apps and then heading over to my dummy online shop.

If you select to pay with TommyPay on this merchant page, it tries to call PaymentRequest.show(), while intercepting the NOT_SUPPORTED_ERR exception. If this payment method is not supported, it redirects to the signup page for TommyPay. This code looks something like this:

request.show()
.then(function(paymentResponse) {
    // handle successful payment
})
.catch(function(error) {
    console.log("show() error: " + error);
    if (error.code == DOMException.NOT_SUPPORTED_ERR) {
        window.location.href =
            "https://tommythorsen.github.io/webpayments-demo/payment-apps/tommypay/signup/?redirect_url=" +
            encodeURI(window.location.href);
    }
});

Since we pass the url to the current page as redirect_url to the signup page, the signup page is able to redirect back to the merchant upon successful signup, so that the checkout process can continue seamlessly.

Does this meet the needs of a recommendation system, or are we missing something important? It would certainly be possible for the merchant to show some intermediate UI, asking the user if they want to install TommyPay before redirecting there.

There's one use-case that is hard to support in this way: you may have noticed that I have separated the payment actions into individual buttons for the individual payment methods. For some merchants, this may not be desirable - they may wish to have one payment button that contains all their supported payment methods. In such a scenario, since most user agents have native support for basic-card, PaymentRequest.show() will never throw a DOMException.NOT_SUPPORTED_ERR. This leaves the merchant no opening to do recommendations, even if they would really prefer to nudge the customer to use something other than basic-card. This case would have worked better if the user agent could display both the set of installed payment methods, and the set of recommended ones simultaneously.

This example does not make use of PaymentRequest.canMakePayment(). Depending on how we want this function to work, we may open up more possibilities for merchants to do recommendations in other ways.

(let try that again 😓)

Does this meet the needs of a recommendation system, or are we missing something important?

IMO, yes - that meets the needs for V1.

At today's payment apps task force call [1] we concluded that we want to put a marker in the FPWD indicating that we want additional input on two capabilities (not currently in the spec):

1. recommended unregistered payment apps
2. merchant information to enable highlighting of certain registered payment apps

Ian

[1] https://www.w3.org/2017/04/04-apps-minutes#item06