Home
Status May 2019: The Web Payments Working Group plans to revisit use cases supported by Payment Request API version 1, and nearby use cases that might be achievable with some modest changes or additions. This is a document in development and does not reflect any consensus.
Web Payments Working Group participants interested in this work: Zouhir Chahoud (Microsoft), Adrian Hope-Bailie (Coil), Frank Hoffmann (Klarna), Ian Jacobs (W3C), Chris Marconi (Capital One), Danny Russell (Worldpay), Rouslan Solomakhin (Google), Justin Toupin (Google), Laura Townsend (MAG), TBD (Shopify).
Others interested in this work: Puneet Shah (Adyen).
Payment Request API enables a user to complete a transaction more easily by reusing information stored in the browser or third party payment handlers. The Web Payments Working Group (WPWG) anticipates that version 1 of the specification will be completed in 2019.
To help identify and prioritize enhancements to the next version of the API, the WPWG intends to use this wiki to identify:
- The primary use cases enabled through Payment Request API 1.0.
- The primary "nearby" use cases and enhancements to the API that would enable them.
- Use cases that, at this time, the WPWG considers are better handled through other approaches (e.g., Web form in conjunction with autofill).
The WPWG uses several terms in specific ways:
- Payment Method. An ecosystem for making a payment, such as a credit card payment, credit transfer, direct debit, cryptocurrency, or any of the "*Pay" methods. A payment method is characterized by an identifier (a "payment method identifier") and the request/response data model used by stakeholders in corresponding payment flows. In practice, the payment method identifier is either a URL or a short string (more on this later). A merchant declares its accepted payment methods in this ecosystem.
- Payment Instrument. Whereas a payment method is a data model (a sort of template), a payment instrument is an instance of that model. Thus, the "basic card" payment method (template) includes "cardholderName" and "cardNumber" and a specific payment instrument might set cardholderName="Jane Smith" and cardNumber="5500 0000 0000 0004."
- Payment Handler. A piece of software (Web page, native app, or built into the browser) capable of handling a request for payment on behalf of the user. A payment handler provides one or more payment methods. In the Web payments ecosystem, the user selects a payment instrument managed by a payment handler, and returns that data to the merchant Web site.
- Mediator. The mediator manages the communication between the merchant (or whoever is requesting payment), the payment method owner (if there is one), and the payment handlers available to the user. Payment handlers tell the mediator (through Web or proprietary protocols) which payment method(s) they support through registration with the mediator. In most cases, the browser fulfills the role of mediator, but other software may also fulfill this role.
- Payment Method Owner The entity that oversees or controls the data model, rules, and other processes of a payment method. A payment method owner authorizes payment handlers to fulfill the payment method. Standardized payment methods (e.g., such as the Basic Card Payment Method from W3C) do not have an owner. A payment method owner can authorize which payment handlers are authorized to fulfill that payment method; this is done through a payment method manifest. The mediator only shows payment handlers to the user that are authorized by a payment method manifest.
Note:
- In many cases, the entity that owns a proprietary payment method may be the only entity that distributes a payment handler for that payment method. In that case, the payment method and the payment handler often share the same name.
The following diagram illustrates the generic Payment Request API 1.0 flow.
- For most payment methods, the payer enrolls (sets up an account) with various payment service providers. This includes setting up a card account, online payment service account, bank account, distributed ledger wallet, etc. The payer then provides credentials to payment handlers and registers those handlers with user agent(s) that support the API.
- The payee (whether merchant or PSP) builds a checkout experience using the W3C API instead of a Web form. In the description below, we simplify by referring only to the payee. The APIs do not change how merchants and their payment service providers relate.
- The payer pushes the "buy" button on the payee Web site.
- The payee Web site invokes the Payment Request API, with information about accepted payment methods (such as the Basic Card payment method and transaction details (e.g., price, currency, items being purchased).
- The mediator computes the intersection of payment methods accepted by the payee and those supported by the payer's payment handlers. The Payment Method Identifiers specification discusses payment method identifier syntax and matching.
- The mediator displays to the payer the list of payment handlers that can be used for transaction (because they implement the intersection of payment methods). The Payment Handler API specification defines how Web-based payment handlers participate in this flow.
- The payer selects a payment handler one to pay.
- The mediator provides transaction details and payment method-specific data from the payee to the payment handler. The user agent then delegates control to the payment handler.
- The payer interacts with the payment handler. Payment handlers will vary greatly in the kinds of user interactions they support, for example, whether and how they support authentication, what services they offer in addition to payments, and the user experience optimizations they provide.
- When payee interaction with the payment handler completes, the payment handler communicates response data back to the user agent, including data specific to the payment method and status information.
- The payment handler is closed and returns control to the mediator.
- The mediator returns the payment handler response to the payee.
The data the flows through the Payment Request and Payment Handler APIs is payment method specific.
- Payment request anticipates that the mediator may make available the following information upon request: payerName, payerEmail, payerPhone, shippingAddress, shippingOption. We are discussing enabling user agents (with payee permission) to forward the request for that data to the payment handler. This may enable more "skip the sheet" user experiences for payment handler-stored data. Note that the choice of which data the mediator can store depends largely on what data is frequently reused.
- Chrome implements a "skip-the-sheet" optimization for cases where the user does not need to interact with the sheet (e.g., no selection of payment handler, no selection of shipping address, etc.). In this case, Chrome hands control directly to the lone matching payment handler. This optimization did not require any changes to any API.
- Payment Handler API defines the information exchanged at registration, launch, and completion.
- Chrome supports a "just-in-time" registration by leveraging payment method owner default preferences in a payment method manifest information, but this is not defined in Payment Handler API.
- Not yet implemented but under discussion: When there is no payment method owner or no default preference expressed, browsers may also offer default payment handler(s) for a payment method. It is not clear that this requires any changes to any API.
- Payment Handler API supports instrument level display and selection of information in the sheet. The idea is to allow the user to rapidly identify and select an instrument, and then to launch the relevant payment handler with information about the selected instrument. This is designed to reduce friction and the number of clicks to payment. Although this feature has been specified, no mediator yet implements it.
The following topics should be considered out of scope for Payment Request API enhancements. Of course, a use case description or flow might refer to "authentication" but that functionality will be addressed through other technology than Payment Request.
- Cryptography. But see Web Crypto API and the draft work on Encryption for payment methods
- Authentication. But see Web Authentication API
- Network security (e.g., TLS)
- Hardware protocols (e.g., NFC, Bluetooth). But see Web NFC and Web Bluetooth.
- Verifiable claims. But see Verifiable Claims WG
- User experience of enrollment of instruments
- Payment handler communication with servers
- Information storage (e.g., how do payment handlers store credentials)
- Payment initiation from native apps
Notes:
- The Web is available on many kinds of devices. These use cases do not call out particular device contexts (e.g., mobile).
- In this initial pass, there is no distinction between "use cases" and mere "feature requests." That is because in some cases, the feature definitions are the result of description of use cases in GitHub.
- For any payment method, merchant can request user name, user phone, user email, shipping address and some options, and payment credentials.
- Implementations can address a variety of "readiness" scenarios:
- User has a registered payment handler with instrument primed to pay
- User has a registered payment handler but needs to add an instrument
- User does not yet have a payment handler but the mediator assists automatically based on payment method owner-provided data.
- User does not yet have a payment handler but the mediator assists automatically based on mediator-provided data.
We will want to evaluate whether these should be in scope, postponed, or best addressed through other Web technologies.
- Alternative button wording. Enum or string?
- Add more details (icons, labels)
- Help strings for requested fields
- New approach for gesture to invoke sheet
- New approach to show supported methods before sheet
- Enable payee to specify additional branding within sheet. (Need specific suggestions here.)
- Ability to use Payment Request API for information capture within a merchant-owned checkout experience, instead of presenting a checkout box outside the merchant experience (behind the scenes to the guest).
- Ability to request data not just at payment request construction time, but also at other times during the transaction (even if not requested at construction time).
- Proprietary gift card combined with another payment type
- Discount codes
- Ability to apply tender discounts (only the portion of the cart which is tender-eligible in the case of multi-tender)
- Custom shipping info
- In-store pickup
- Merchant-specified default shipping address
- Alternate shipping address
- Pre-calculate shipping cost for N addresses
- Pre-filter shipping addresses by country
- Ability to have multiple delivery methods in a single cart (at least pick up in store and shipping items)
- Ability to have multiple shipping addresses in a single cart (items for me and gifted items sent directly)
- Ride sharing and other optional total use cases
- Pre-authorization
- Aborting in-progress push payments
- Agreement to terms and conditions]
- Notification to payment handler post-authorization
- Drop support for Push Payments
- Disbursements to multiple payees
- hasEnrolledInstrument
- Payment handler identity in response data
- Fine-grained error reporting with canMakePayment()
- On the fly merchant validation and registration
- See also the Payment Handler issues list
Based on previous discussions, the current consensus is that these use cases are addressed outside of Payment Request API, potentially simply through other Web technologies, or in a payment method definition, on the back end, etc.
- Payment Request API is well-suited to the initial capture of payment information. Recurring payments rely on reuse of stored data and to not require returning to the user. Therefore, they are best addressed through back end processes.