Skip to content

PaymentApp_Notes

Jump to bottom
ianbjacobs edited this page Jan 24, 2017 · 223 revisions

Status:

  • Notes initiated by Ian Jacobs that are being migrated to the Payment App API specification.
  • A WG task force is turning these notes into a specification. The task force includes:
    • Adrian Hope-Bailie (Ripple)
    • Ian Jacobs (W3C)
    • Mahesh Kulkarni, Alan Marshall, Dongwoo Im (Samsung)
    • Kepeng Li (Alibaba)
    • Roy McElmurry (Facebook)
    • Andre Lyver, Jason Normore (Shopify)
    • Adam Roach (Mozilla)
    • Pascal Bazin, Laurent Castillo (Gemalto)
    • Conor Hackett (Worldpay)
    • Ken Mealey, Huw Bailey, Faraz Babar, Ben Smith (Amex)
    • Rouslan Solomakhin (Google)
    • Frank Hoffman (Klarna)
    • Tommy Thorsen (Opera)
    • Michelle Bu, Stan Polu, Jenan Wise (Stripe)
  • As of 10 January 2017, the task force meets weekly on Tuesdays at 10am ET. WebEx info
  • Minutes: 24 Jan, 17 Jan,12 Jan dev sync up, 10 Jan, 4 Jan 2017, 14 Dec, 7 Dec, 30 Nov, 23 Nov, 16 Nov, 2 Nov, 19 Oct, 5 Oct, 14 Sep, 31 Aug, 24 Aug, 17 Aug,10 Aug, 3 Aug, 27 July, 20 July, 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:

Platform integration documentation:

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

Payment App Response Handling

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

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.

Design Considerations

Decoupling and trust

  • A goal of this system is to decouple the payment methods used to pay from the software (payment apps) that implement those payment methods. By decoupling, merchants (and their payment service providers) can lower the cost of creating a checkout experience, users can have more choice in the software they use to pay, and payment app providers can innovate without imposing an integration burden on merchants.
  • Users may choose to use "open" or "proprietary" payment methods, so the payment app ecosystem must support both. Users must be able to register payment apps of their choosing. We expect the user to have greater choice of third party payment apps for open payment methods than for proprietary payment methods. Examples of open payment methods include card payment and SEPA credit transfer.
  • For privacy, the design should limit information about the user's environment available to merchant without user consent. That includes which payment apps the user has registered. For open payment methods, the merchant should not receive information about which payment app the user selected to pay unless the user consents to share that information.
  • Although decoupling relieves merchants of implementing some aspects of the checkout experience, one consequence is that they give up some degree of control. This was already the case for proprietary payment methods, but for open payment methods such as cards, merchants (or their PSPs) will be entrusting some portion of data collection to third party payment apps, without knowing which app the user will select.
  • We recognize, therefore, a tension between user preferences (e.g., registered payment apps, ordering of display of payment apps, etc.) and merchant preferences (e.g., control of the user experience previously implemented in a Web page, ordering of payment apps, presence of merchant's own payment app, etc.).
  • The design should address this tension by enabling the merchant to express preferences for both payment methods and payment apps. The design should not constrain how browsers make us of these preferences, only provide guidance to browser vendors about taking into account both merchant and user preferences.
  • Here are preferences the system might support:
  • Accepted payment methods (payment methods the merchant accepts, and no others may be used; part of payment request API)
  • Preferred payment methods (merchant-specified order part of payment request API)
  • Recommended payment apps (payment apps the merchant prefers, but others may be used)
  • Accepted payment apps (payment apps the merchant accepts, and no others may be used). Note that this is the status quo since merchants either accept card information through UI that they control, or they redirect users to payment service providers with whom they have existing relationships. Note that if we allow merchants to restrict payment apps that might end up requiring the customer to install multiple payment apps for the same payment method, which would complicate the user experience for the same payment method.
  • The browser uses this information in conjunction with user preferences to:
  • Filter matching payment apps (in the case of accepted payment apps)
  • Display matching payment apps (according to merchant preferred payment method order)
  • Display recommended payment apps (according to merchant recommended payment app order)

Payment App Identification

  • For both "recommended" and "accepted" payment apps, we will need payment app identifiers (PAIs).
  • A PAI should include origin information. This origin information may be used in a variety of ways:
    • The origin information could enable browsers to provide the user with useful services when the user is browsing a site with the same origin (e.g., putting that payment app at the top of a list or otherwise highlighted).
    • For a "proprietary" payment method with an associated origin, the browser can do some (security) checks by comparing the origin of the payment method and the payment app.
  • A PAI should allow for granularity (e.g., payment app versioning); we should consider URLs.

User experience

  • The system should minimize user interaction for payment app registration, payment app selection, and payment credentials selection.

Registration

  • We expect registrations will happen at various times (e.g., outside and inside of checkout): Here are some examples:
    • When the merchant recommends a payment app and the user selects it, registration can happen in that moment without additional user action.
    • When the browser recommends a payment app and the user selects it, registration can happen in that moment without additional user action. (There is an expectation that the display of browser-recommended apps will differ from the display of merchant-recommended apps).
    • When the user installs native payment app, registration can happen as part of the app installation process.
    • Users visiting a Web site (e.g., merchant or bank) may wish to explicitly register payment apps.
  • At the same time, the system should not modify the user's environment or share user data without the user's consent. Consent may be provided in a number of ways that can be streamlined (e.g., registration of a native payment app can happen when the native app is installed; when only one payment app matches merchant-accepted data, the browser can launch the app directly instead of requiring additional user selection; etc.)

Payment app / browser communication

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

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.

Adam Roach wrote: "At a high level: the URL pointing to the payment app would be expected to contain javascript. This JS is loaded into a windowless context. If it needs to display information to the user, it can use window.open() and load its UX into that window. The payment request would be provided by the mediator via some a javascript affordance -- e.g., using window.postMessage() -- which could then be used to provide a response from the script."

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

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.

User Experience Descriptions

Rcmnd apps Reg apps Sup m's Enbl m's Match m's Behavior
0 0 0 0 0 false
Rcmnd apps Reg apps Sup m's Enbl m's Match m's Behavior
0 1 0 0 0 false
0 1 1 0 0 false
0 1 1 1 0 false
0 1 1 1 1 browser SHOULD launch payment app automatically
Rcmnd apps Reg apps Sup m's Enbl m's Match m's Behavior
0 2 0 0 0 false
0 2 1 (in one) 0 0 false
0 2 1 (in one) 1 0 false
0 2 1 (in one) 1 1 browser SHOULD launch payment app automatically
Rcmnd apps Reg apps Sup m's Enbl m's Match m's Behavior
0 2 0 0 0 false
0 2 1 (in both) 0 0 false
0 2 1 (in both) 1 0 false
0 2 1 (in both) 1 1 browser MUST display both for selection
Rcmnd apps Reg apps Sup m's Enbl m's Match m's Behavior
0 2 0 0 0 false
0 2 2 (1 in each) 0 0 false
0 2 2 (1 in each) 2 0 false
0 2 2 (1 in each) 2 1 browser SHOULD launch payment app automatically
0 2 2 (1 in each) 2 2 browser MUST display both for selection
Rcmnd apps Reg apps Sup m's Enbl m's Match m's Behavior
1 0 0 0 0 browser SHOULD display recommended app, registered on selection
1 1 (same as merchant) N 0 0 browser SHOULD display recommended app with indication that it is recommended for this merchant but needs to be enabled
1 1 (same as merchant) N > 1 0 0 browser MAY display user's app with indication that merchant recommends but needs to be enabled
1 1 (same as merchant) N > 1 M > 1 R > 1 browser MUST display matching app
1 1 (not same as merchant) 0 0 0 browser SHOULD display recommended app, registered on selection
1 1 (not same as merchant) 1 1 1 browser MUST display matching app, SHOULD display recommended app and differently
1 2 1 1 1 browser MUST display matching app, SHOULD display (non-matching) recommended app and differently
1 2 2 (1 in each) 2 2 browser MUST display both matching apps, SHOULD display non-matching) recommended app and differently
Rcmnd apps Reg apps Sup m's Enbl m's Match m's Behavior
0 1 0 0 0 browser SHOULD display accepted app with indication that merchant only accepts this app, app is registered on selection
0 1 1 1 1 browser MUST display matching app if same as accepted; MUST NOT display user's matching app if different than accepted. In latter case, SHOULD display accepted app with indication that merchant only accepts this app, app is registered on selection

Notes

  • "False" means "no display and no user interaction; payment request API returns false."
  • Recommended means "merchant likes these but user can use others that match on payment method."
  • If the system supports browser-recommended apps, those must be identified separately from merchant-recommended apps.
  • Browsers MAY display details about payment instruments to enable direct selection from the browser's display. However:
    • Information about payment instruments MUST NOT be shared with merchant
    • Selection of payment instrument in browser display SHOULD launch payment app with (standardized) indication of which instrument was selected, which allows the payment app to optimize response behavior.
  • We need to call out in the spec the need to get user consent to confirm payment (as a configurable option, for example)

Acknowledgments

Home

How we work

Mailing list archives

Meetings

Issues

Tests

Adoption

Previous Topics

Clone this wiki locally