Skip to content

Home

Jump to bottom
ianbjacobs edited this page Oct 17, 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: 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).

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; see the related blog post
  • 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.
  • In some use cases it may be interesting for the payee to interact with a payment handler after the completion of the Payment Request API. These use cases include:
    • Electronic receipts (that might be stored by a payment handler)
    • Protocols (e.g., SRC) where the the payment system includes a message from the payee back to the payment handler (e.g., with an update about the status of payment).
    • Refreshing a token; see the draft token cryptogram description

Out of Scope

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.

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 (e.g., how do payment handlers store credentials)
  • Payment initiation from native apps

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

Background observations as part of discussion of use cases:

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

Merchant / Customer Relationship Lifecycle

Guest Checkout

  • Consumer does not wish to store any information on the merchant website.

Account Creation

  • During customer account creation, the merchant calls Payment Request to collect data and store it for later use.

Returning Customer Who has not Stored Some Credentials

  • In this scenario, the customer has an account with the merchant but chooses not to save some information in their account.
  • Some consumers may not be comfortable with the merchant storing payment information.
  • Merchants may prefer this flow in some cases for several reasons. If user confidence increases (because the user does not need to store information with the merchant), this may increase conversions. Also, Some merchants may wish to lower their PCI risk or data management costs by not storing sensitive payment credentials.

Returning Customer Who Refreshes Credentials

  • The customer has previously stored payment credentials (e.g., a token) with the merchant, but those credentials can only be used for a limited period before they need to be refreshed, or they may expire (e.g., credit card expiration). For some payment methods and where the merchant has a back-end relationship, it may be possible to refresh credentials without user interaction (e.g., credit card account updater services). However, there may also be use cases where the merchant wishes to have a user interaction to re-confirm usage of credentials, and in this case Payment Request API might be invoked. However, it is likely that we would need to extend the API to support a post-Payment Request API interaction with the payment handler used for a particular transaction.

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

  • Paying with more than one instrument (e.g., a proprietary gift card combined with another payment type, or a credit card in combination with a peer-to-peer payment service).

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

Development Tools

  • Facilities to enable merchants to test Payment Request API in their environments. See our charter.

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.
  • Nevertheless, if Payment Request supports some additional customization, it may be easier to communicate to the user that a particular confirmation will result in a recurring payment. For example, a merchant might wish to customize the text of a button so that instead of "Confirm" the button says "Subscribe" or "Save card in account" to more clearly communicate the nature of the agreement between customer and merchant.

Supporting materials

Clone this wiki locally