Status:

• Notes initiated by Ian Jacobs that are being migrated to the Payment Applications and Browsers specification.
• A WG task force is turning these notes into a specification. The task force includes:
  • Adrian Hope-Bailie (Ripple)
  • Dongwoo Im (Samsung)
  • Ian Jacobs (W3C)
  • Mahesh Kulkarni (Samsung)
  • Kepeng Li (Alibaba)
  • Roy McElmurry (Facebook)
  • Jason Normore (Shopify)
    
  • Adam Roach (Mozilla)
  • Zephyr Tuan (Alibaba)
  • Laurent Castillo (Gemalto)
• Minutes: 16 June, 2 June

Edits by WG participants welcome, as well as comments by anyone to [email protected]. These notes are for discussion and do not represent the consensus of the Web Payments Working Group.

Links to relevant group issues in the text. The document overall relates to issue 12.

See also:

• Spec Notes
• Payment Method Identifier Notes
• Extensibility Notes

Purpose of this Document

• The Web Payments Working Group is defining a suite of technologies to make payments on the Web. The suite will include the ability for users to register payment apps that they may use during checkout.
• This document is part of an ongoing discussion within the Working Group about how the user registers payment apps, how the browser offers those apps to the user during checkout, how the user selects one to pay, how communications take place between payment app and browser, and so on.
• One reason for the document was to prompt discussion about different methods for invoking payment apps.

Definitions

Payment App Source Technology

• browser-based payment app: a payment app that runs in a browser.
• headless payment app: a payment app that has no user interface but communicates using Web technology (such as HTTP). For example, one could set up an HTTP server that receives payment requests via an HTTP request and returns a response via HTTP. User experiences include using a native mobile app with out-of-band communication via HTTP, IOT payments, and configuration by the user to make payments automatically.
• web-based payment app: a payment app built using Open Web Platform technology. This includes both browser-based payment apps and headless payment apps.
• native payment app: a payment app built with the operating system default technology stack that uses non-Web technologies. See issue 50.

Payment Method Support

• supported payment method: a payment method the user can configure the payment app to support.
• enabled payment method: a payment method the user has configured the payment app to support.
• unsupported payment method: a payment method the user cannot configure the payment app to support.

Payment App Status

• registered payment app: a payment app that the user has successfully registered with the browser.
• unregistered payment app: a payment app that is unknown to the browser, either because it has never been registered, or it has been unregistered.
• enabled payment app: a registered payment app with at least one enabled payment method.
• ignored payment app: a payment app that, per user configuration, the user agent does not display as matching and does not invoke for payment. A payment app may be ignored for some transactions and not ignored for others. For instance, if a browser allows a user to configure a default payment app for a particular Web site, other payment apps are considered ignored for that site.
• matching payment app: an enabled payment app that:
  • has at least one enabled payment method that the payee accepts.
  • is not an ignored payment app.
• recommended payment app: an unregistered payment app recommended by the payee or browser. See issue 155.
• displayed payment app: a matching or recommended payment app presented by the browser for user selection.
• selected payment app: a displayed payment app selected by the user to process a payment request for a given transaction.
• invoked payment app: a selected payment app that the browser has invoked by passing it a payment request.

Payment Data

• paymentRequest API input: Data provided by the payee's Web application to the browser via the paymentRequest API.
• paymentRequest API response: Data provided to the payee's Web application by the browser after completion of the paymentRequest API.
• payment app input: Data provided to the invoked payment app by the browser. This data is likely be a subset of the paymentRequest API input (e.g., payment method, payment method specific data, and transaction specific data). See issue 157
• payment app response: Data provided by the invoked payment app to the browser. See issue 97 about required response data.

Scope of this document

• This document is limited to discussion of web-based payment apps.
  • Question for group. The group needs to decide whether the scope of its initial work will be web-based payment apps or (the subset) browser-based payment apps.
  • See issue 39 and notes from Wayne Carr.
  • Note that we anticipate that there will be native payment apps, but we may not be able to establish a "cross-native-platform" way for browsers and native payment apps to communicate. That is why our initial standardization effort is focused on Web-based payment apps.
• This document assumes that the browser is fulfilling the role of mediator. If the mediator is distinct from the browser, it will be necessary to describe their communications.
• This document does not discuss the computation that determines a "matching payment app".
  • We have discussed separately computing the intersection of payee-accepted payment methods and user enabled payment methods. The matching algorithm should be defined elsewhere.
  • A system that allows specification of relationships among payment method identifiers (e.g., subclass relationships or set exclusion) will result in a more complex matching algorithm; see Payment Method Identifier Notes.
  • See issue 110.
• This document does not (yet) discuss how a payment app communicates registration information to the browser (e.g., via a manifest or some other mechanism). See Issue 130.
• This document does not (yet) include registration information requirements related to payment app display (e.g., for branding). See notes from AHB on sharing payment instrument information for mediator display.
• This document assumes the user may select a single displayed payment app for payment. (@ianbjacobs urges the Working Group to postpone multi-tender payments to a future version of the API, along with coupons, loyalty points, etc.)
• This document does not (yet) discuss how the paymentRequest API input is converted to the payment app input, or how the payment app response is converted to the paymentRequest API response. The description below should still be relevant whether or not conversion is required.
  • See issue 146, issue 154, issue 157.
• This document does not (yet) discuss handling of exceptions after payment app invocation (e.g., user cancellation of a transaction from within a payment app, authorization failure, or other scenarios).
  • See issue 128
• This document does not focus on issues of security, privacy, accessibility, or internationalization, all appropriate in future specifications.

Payment App Lifecycle

Registration and Update by the User

• The user must be able to register or update a payment app with a browser.
  • See issue 111
• During registration and update, a payment app:
  • must provide the following information:
    • Origin (URL) associated with the distributor of the payment apps (native or Web). This could be used later to improve the display of a payment app associated with the origin of the payee's Web application. However, this could also be used for spoofing.
    • Supported payment methods
    • Enabled payment methods
    • Invocation information
  • may declare unsupported payment methods
  • may declare enabled payment instruments (to improve per-instrument information like pricing or list details).

Unregistration by the User

• The user must be able to unregister a registered payment app (that is, turn it into an unregistered payment app).

Payment App Display by the Browser

Note: In general, W3C does not define display requirements. In the case of payments, by moving payment app selection to the client-side, we create some new requirements derived from some merchant contractual obligations. Therefore, we anticipate some form of display requirements, but we still do not want to over-specify browser behavior.

When the browser displays payment apps for selection by the user during a transaction:

• The user agent must display all matching payment apps.
• The user agent may display recommended payment apps.
• The browser must distinguish for the user matching payment apps from recommended payment apps.
• The browser should display matched payment apps in an order that corresponds to the order of supported payment methods supplied by the payee.
• The browser should display any payee-recommended apps in the order specified by the payee.
• The user agent may allow the user to configure the display of matching payment apps
  • Example: The user agent might allow the user to display a preferred payment app "at the top of the list."
  • Example: The user agent might allow the user to set a default payment app for a Web site and only display that payment app (until configured otherwise).
  • Example: the user agent might allow the user to affect the display of a payment app associated with the payee's Web application, for example by listing it "at the top of the list." See issue 112.
• If the browser is in incognito mode, it MUST make the user aware of the transition of focus to a payment app, or prevent it.
• Web-based payment apps MUST run in a secure context.

Payment Details Display by the Browser

• If the browser displays payment details, it should do so in the order specified by the payee.

Payment App Selection by the User

• The user must be able to select any displayed payment app.
• Selection of a recommended (but unregistered) payment app should lead to payment app registration before invocation.

Payment App Invocation by the Browser

• The browser must invoke a selected payment app with payment app input data.
  • See issue 130

Invocation approaches

JavaScript encapsulation

This approach (explored in the WebRTC specification) involves providing the browser with some JavaScript at registration time. Invoking the payment app means executing the JavaScript with payment app input data. The JavaScript may do any number of things, including HTTP calls to a server or client-side operations.

• Advantages:
  • Flexible, as it does not require agreement on a single HTTP interface. It also allows the payment app provider to manage client and server communications as they prefer.
  • Some (larger?) payment providers already have JavaScript SDKs.
  • Capable of adhering to the Web security model (same-origin)
• Disadvantages:
  • A fairly new approach for interaction between Web applications and other applications.
  • Most existing payment gateways process HTTP requests so this will require all of these to make significant investment in new technology to accept payment requests from the browser.
  • Defines a standard for cross application integration at the language level as opposed to at the protocol level. This forces all payment apps (or at least part of them) to be written in JavaScript.

HTTP

This approach involves providing the browser with a URL to an HTTP server at registration time. Invoking the payment app means using HTTP POST to send it payment app input data.

• Advantages:
  • Familiar Web technology. Favors the platform over a particular language environment.
  • Most payment gateways already accept payment requests via HTTP. They can add a new HTTP endpoint to their existing HTTP API that accepts a payment request and transforms this into the format they receive on other end-points. For most gateways this is very familiar part of their operations and would dovetail into their existing systems much more easily than the JavaScript approach.
  • Client-side only payment apps can be implemented using ServiceWorkers that intercept the POST and handle it locally using respondWith().
  • It is conceivable that defining communication with payment apps via HTTP will fulfill the part of the WG charter that talks about HTTP-initiated payments.

Payment App Response Handling

• The browser must provide the paymentRequest API response to the payee's Web application.

Response approaches

JavaScript encapsulation

At some point (after authorized payment, cancellation, or other scenarios) the browser-based payment app calls a browser API submitting the payment app response. The browser converts the payment app response to the paymentRequest API response. The promise associated with the invocation of the paymentRequest API resolves with the paymentRequest API response.

HTTP

The browser receives the payment app response via HTTP. The browser converts the payment app response to the paymentRequest API response. The promise associated with the invocation of the paymentRequest API resolves with the paymentRequest API response.

Hybrid

The browser receives an HTTP response after sending the payment app input via HTTP POST. Using content-type negotiation and/or redirects it determines if there is a browser-based payment app UI it must display. If the HTTP response is a valid payment app response (JSON encoded and matches a given schema) then the browser converts the payment app response to the paymentRequest API response. If the HTTP response is HTML the browser renders this as a browser-based payment app and at some point (after authorized payment, cancellation, or other scenarios) the browser-based payment app calls a browser API submitting the payment app response. The promise associated with the invocation of the paymentRequest API resolves with the paymentRequest API response.

• Advantages
  • If the user has setup rules in the payment app to authorize certain payments automatically (e.g., from certain merchants below certain values, etc.) the payment app could simply respond with a JSON-encoded payment response and the browser would never need to render any payment app UI.
  • It supports the case where the payment app wants to redirect the request to native app. This can easily be supported by doing a redirect to a URL with a custom URL protocol.

Questions about Failure Modes

• Communication may fail at different times, for instance: ** Between payment app and servers it talks to ** Between browser and payment app ** Between browser and merchant
• How will we address different failure modes for payment apps?
• Will we differ in what we do or expect between Web-based and native?
• Should we recommend asynchronous communication between payment app and servers it talks to? Between browser and payment apps? In the background between payment apps and merchants?

Data Collection

Collected data is likely to include (optionally in some cases):

• Transaction-specific information (e.g., amount, currency, etc.)
• Payment method information (e.g., supported or unsupported payment methods)
• Input and output data specific to a selected payment method
• Instructions from the payee (e.g., capture shipping address, where payment method data is optional whether it is mandatory for a given transaction; see issue 97).

There are multiple entities that might collect this data during a transaction. Here are some considerations for when an entity might be the right choice to collect data.

• Collect in payee Web app when:
  • The data relates exclusively to the user's ongoing relationship with payee outside of this transaction.
  • The data is required independent of selected payment method and the browser/mediator does not support its capture.
  • The data affect the e-Commerce flow prior to payment.
  • The data could influence the choice of payment app.
  • The data is specific to this transaction and independent of payment method (e.g., discount code).
  • The Web Payments Working Group charter explicitly puts that data out of scope for the payment APIs.
• Collect in browser/mediator when:
  • The data could influence the choice of payment app.
  • The data is common to many payment methods and across many payees.
  • The data affects the total price (e.g., shipping address, discount code).
  • The data can be widely reused across payees and payment methods (e.g., shipping address) and caching by the browser will improve the user experience.
  • The data is specific to this transaction and independent of payment method (e.g., discount code).
• Collect in Payment App when:
  • The data is required by a given payment method.
  • The data relates to the user's ongoing relationship with the distributor of the Payment App. Note: If the payee and the distributor of the Payment App are one and the same, then the Payment App may be a way to refine the user experience for features not yet supported in the mediator/browser. Example: the input payment data could include a callback URL so the Payment App can complete the entire payment processing flow and only return focus to the browser/mediator when it has confirmed the payment.
  • The Web Payments Working Group charter explicitly puts that data out of scope for the payment APIs.

Payment App Display of Payment Items

• If the payment mediator exposes the displayItems to the user, it MUST expose all of them in the order in which they were supplied.

Acknowledgments

• Thanks to Zach Koch for the Payment App Registration Explainer
• Thanks to Adrian Hope-Bailie for drafting Payment apps.
• Thanks to Dominique Hazael-Massieux for discussion of ways to invoke a payment app.
• Taxonomy of Mobile Application Platforms