Skip to content

Home

Jump to bottom
ianbjacobs edited this page May 9, 2019 · 70 revisions

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), 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).

Introduction

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).

Terminology

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.

Payment Request 1.0 Flow

The following diagram illustrates the generic Payment Request API 1.0 flow.

Payment Request 1.0 Flow

Description of Flow

Before a Transaction

  • 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.

During a Transaction

  • 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.

Components and Specifications

Payment Request Ecosystem Components

The data the flows through the Payment Request and Payment Handler APIs is payment method specific.

Payment Request 1.0 Ecosystem Scope Notes

Payment Request

  • 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 Handlers

  • 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.

Out of Scope

Out of Scope because not in WPWG Charter

Out of Scope for other reasons

  • User experience of enrollment of instruments
  • Payment handler communication with servers
  • Information storage

Use Cases

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.

Version 1.0

Guest Checkout

Data Capture for User Account

Potential Enhancements after Version 1.0

We will want to evaluate whether these should be in scope, postponed, or best addressed through other Web technologies.

UX and Styling

Increased Request Granularity

Multi-Tender

  • Proprietary gift card combined with another payment type

Discounts

  • Discount codes
  • Ability to apply tender discounts (only the portion of the cart which is tender-eligible in the case of multi-tender)

User Data in Response

Shipping

Address Components

Payment Flows

Interaction with Payment Handlers

Out of Payment Request API Natural Scope

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.

Recurring Payments

  • 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.

Implementation status

Supporting materials

Clone this wiki locally