When using Payment Request API, merchants want some assurances about the nature of the user’s payment journey. The decision to use Payment Request for a given payment method might depend on answers to these questions:
- Does the user have access to a payment handler at all?
- Does the user have a payment handler that is immediately ready for payment?
A “yes” answer to the second question is useful when the merchant wants the greatest assurance of minimal friction for the user to complete the payment.
However, in some cases, the merchant might prefer a particular payment method and accept more friction —the user might have to sign up for an account or adding an instrument to the payment handler before completing payment. A “yes” to the first question is useful for this case.
Payment Request includes two methods corresponding to the two questions: canMakePayment and hasEnrolledInstrument. Here’s how we expect them to work.
canMakePayment
The method returns “true” when either of the following is true:
- The browser knows of at least one registered payment handler for this payment method. The payment handler might be built into the browser, a Web-based payment handler registered through Payment Handler API, or a native app registered through some other platform-specific mechanism.
- The browser is capable of registering a payment handler on-the-fly, for instance using information made available by the payment method owner in a payment method manifest.
Note that for canMakePayment(), the browser is not required to launch or communicate with any payment handlers.
hasEnrolledInstrument
In order to know whether, for a given payment method, the user has at least one payment handler with an enrolled instrument, the browser delegates the question to each payment handler registered to support that payment method. A payment handler returns “true” when it has an enrolled instrument. I think each payment method (whether proprietary or standardized) will define what “having an enrolled instrument” means.
Here is some fodder for those hasEnrolledInstrument discussions (e.g., around Secure Remote Commerce or ACH):
- If the payment handler requires authentication (at some point), does the payment handler return “true” only after authentication?
- Assume the merchant has some knowledge of the user’s identity (e.g., an email address). Does the payment handler return “true” only if there is an enrolled instrument associated with that identity? Presumably the merchant would provide the identifier in the payment method-specific request data, and the payment handler could consult it as part of answering hasEnrolledInstrument.
- If the payment handler validates an account (e.g., for sufficient funds), does the payment handler return “true” only after successful validation?
If you have other use cases where similar considerations would affect the payment handler’s response, please let us know.
Specification Notes
The Payment Request API 1.0 specification only defines canMakePayment. The Editors’ draft, which is a living specification, also defines hasEnrolledInstrument. Deployed browsers (including Chrome and Safari) are starting to support it. We expect to include the method “officially” in Payment Request after we publish the final Recommendation of version 1.
The Payment Handler API defines an event to enable Web-based payment handlers to respond to the browser’s delegation of hasEnrolledInstrument(). Alas, the Payment Handler API specification is not up-to-date with our naming choices. Thus, it is currently named CanMakePaymentEvent. Of course we plan to change that to hasEnrolledInstrumentPaymentEvent; perhaps this blog post will hasten that fix.
Privacy Expectations
Because canMakePayment() and hasEnrolledInstrument() methods have the potential to expose user information, browsers are expected to protect users from abuse. We discuss privacy protections in the Payment Request API spec. Our discussions about user experience (e.g., user consent for the payment handler to respond to hasEnrolledInstrument queries) are ongoing. We welcome your input on this topic.