The mission of the Web Payments Working Group is to make payments easier and more secure on the Web.

The group is chartered to develop multiple technologies. This document describes an architecture and a set of roles in that architecture that, together, facilitate the group's mission.

This intentionally describes components by their role, acknowledging that different implementations may result in multiple roles being adopted by a single system component. No specifics are defined about how the functions of each role will be fulfilled beyond the internal algorithms that each must execute. Specific interfaces may be described in detail in accompanying documents that define how these roles are implemented in those contexts.

This architecture is focused on the interactions between a payer and payee on the Web and does not cover the architecture or components required for the full end to end payment process.

The working group maintains a list of all bug reports that the group has not yet addressed. This draft highlights some of the pending issues that are still to be discussed in the working group. No decision has been taken on the outcome of these issues including whether they are valid. Pull requests with proposed specification text for outstanding issues are strongly encouraged.

This specification was derived from A Payments Initiation Architecture for the Web.

Design Decisions

Improve the payment experience for payers

Payments on the Web today are very payee-centric. The entire payment process is driven by the payee, usually an online merchant, who presents the user with one or more ways to pay. In the majority of cases the user provides a static credential (such as the details of a credit card) back to the merchant or is redirected to a digital wallet service where they approve the transaction.

Unless the user is able to find a digital wallet that is supported by all of the payee's they wish to pay they will never have a standardized payment experience and the majority of the time that experience is driven by the payee.

Further, there is no standardized mechanism to establish a bi-directional channel of communication between the payer (or their service provider) and the payee (or their service provider) which could be used to exchange payment details and credentials in a more secure manner or negotiate the use of an entirely new payment method.

To remedy this one-sided situation this architecture proposes a new standardized component, the payment app, that is used by the payer to handle payment requests.

Protect payer privacy

Facilitating an autonomous process for matching the payment methods that the payer supports with those that the payee supports seems trivial on the surface, however it is also important to ensure that the architecture doesn't allow for user data to be leaked to the payee system.

To protect the payer's privacy the architecture defines the role of a payment mediator that sits between the payer and payee mediating the initial handshake between them and connecting the requesting payee system with an appropriate payer payment app.

Definitions

In this document we use the following terms with the implied definition as stated below:

Payer
A payer is implied to mean any system operated by (or on behalf of) the payer. This includes systems operated by the payer's payment services provider.
Payee
A payee is implied to mean any system operated by (or on behalf of) the payee. This includes systems operated by the payee's payment services provider.
Payment Request
A payment request is a request from a payee to be paid. It contains the details of what to pay and how the payment can be made. How the payment can be made is specified as a list of payment method identifiers. The payment request MUST contain all of the payment method data required for each payment method identified in it's set of supported payment methods.
Payment Response
A payment response is a response to a payment request (normally the result of processing by a payment app). The content of a payment response will be dependant on how the payment is being processed.
Payment App
A payment app is a component that fulfills the conformance criteria specified for a payment app in this specification.
Payment Mediator
A payment mediator is a component that fulfills the conformance criteria specified for a payment mediator in this specification.
Payment Method
A payment method defines how a payment request must be processed. It defines the format and content of the payment request and payment response messages that are exchanged with a payment app. A payment app must be able to process payment requests for one or more payment methods.
Payment Method Data
Payment requests and payment responses have a limited set of data elements that are common to all payments, irrespective of the payment method. However payment methods can define additional custom data that is specific to that payment method. This custom data is called payment method data.
Payment Method Specification
A payment method specification defines what payment method data is required inpayment requests and payment responses for a particular payment method. It also lists the payment method identifiers that are defined for that payment method.
Payment Method Identifiers
Payment Method Identifiers are defined in [[!METHOD-IDENTIFIERS]]

This specification defines two classes of products:

Payment App

A payment app MUST behave as described in this specification in order to be considered conformant. In this specification, payment app means a software component that exercises the role of a payment app as described in the section Roles.

An informative summary of the required capabilities of a payment app are:

  • It makes available a list of the payment methods for which it is able to process payment requests.
  • It accepts and processes payment requests that conform to the requirements for one of the payment methods it supports.
  • It returns payment responses that conform to the requirements of one of the payment methods it supports and one of the payment methods that was listed as supported in the original request.

Payment apps MAY implement algorithms given in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms.

Payment Mediator

A payment mediator MUST behave as described in this specification in order to be considered conformant. In this specification, payment mediator means a software component that exercises the role of a payment mediator as described in the section Roles.

A summary of the required capabilities of a payment mediator are:

  • It maintains a record of the available payment apps that it is able to pass payment requests to.
  • It maintains a record of the payment methods that each of these payment apps supports.
  • It accepts payment requests and, using algorithms, user input or a combination of the two, determines which payment app to pass the payment request on to.
  • It accepts payment responses back from the payment app and passes these on to the originator of the corresponding payment request.

Payment mediators MAY implement algorithms given in this specification in any way desired, so long as the end result is indistinguishable from the result that would be obtained by the specification's algorithms.

Payment Request Flow

The flow of a payment request is shown in the diagram below:

In this flow, any system or system component playing the role of payment app or payment mediator is assumed to be controlled by the payer. The payment request originates from the payee and is always processed first by a payment mediator.

It's quite possible that a single component may fulfil both roles or even that the system only supports a single payment app, which is always used by default, and therefor the role of the payment mediator is reduced to simply proxying the request and response between the payee system and the payment app.

Payment Methods

Each payment app will support one or more payment methods. A payment method is a system and set of rules for processing a payment request. This architecture is designed to support the broadest possible array of payment methods. When a payee accepts a given payment method, the assumption is that the payee will know how to process the payment method data returned by the payment app for that payment method.

Each payment method is identified by a payment method identifier. The payment mediator compares payment method identifiers in the payment request to those, known to be enabled in the available payment apps to determine which payment apps to offer the payer to use to process the payment request.

Payment method identifiers support distributed extensibility, meaning that there is not a central machine-readable registry to discover or register payment methods. Rather, any person or entity can define a new payment method as long as they publish a payment method specification that defines:

  1. How a payment app should process a payment request.
  2. What payment method data is expected to be included in the request.
  3. What payment method data is expected to be included in the response.
  4. What payment method identifiers identify this payment method.

Roles

The following are the key roles within this architecture.

Payment App

A payment app is a component able to process a payment request and return a payment response. Banks, merchants, mobile operators, and anyone else who wants to, will make these available. User agents are also likely to take on the role of a payment app, storing payment related information on behalf of the user, as they already do today with passwords, and using this to process certain payment requests. It is expected that payment apps will increase security and privacy by giving users more control over what they share over the network. Payment apps will distinguish themselves through the features and services they provide beyond the required capabilities described here, for example by offering strong user authentication, loyalty program integration, back-channel communications with the merchant for fraud analytics, and so on.

Payment apps should be implementable on desktops, mobile devices, televisions, embedded devices and other devices and operating systems. Payment apps may even be implemented in contexts where they do not have direct access to the Web since they payment app receives payment requests from the payment mediator.

As part of processing a payment request, a payment app MAY render a user interface and/or take advantage of one or more other IO channels for payer or third-party interaction (e.g., with a payment service provider). In some cases, and where supported by a payment method, a payment app may be able to facilitate a payment without immediate user interaction based on prior payer consent. (Example: A Web of Things scenario where the payer is a machine capable of executing payments in accordance with predefined rules and logic).

The composition of a payment app will be platform and deployment dependent and many aspects of how the payment app communicates with the host platform, interacts with the payer and payee, and communicates with third-party services will be determined by the implementer who provides the execution environment for the app, the channels supported by the chosen payment method and the capabilities of the payment mediator, that mediates interactions between the payment app and the payee.

Supported vs Enabled Payment Methods

Payment apps support one or more payment methods. Support for a payment method implies that the app SHOULD be able to process a payment request that conforms to the rules defined in the payment method specification for that payment method and SHOULD be able to return a valid payment response.

However, sometimes an app will be designed to support a specific payment method but the app will not have been configured to process payments using that payment method. This may be due to some payment method data that the payer needs to configure such as a user credential or payment instrument details. In that case the payment app is said to support the payment method but that payment method is not enabled.

For example, a payment app may be capable of processing a basic credit card payment that simply returns the card details in the payment response. Unless the user has configured the payment app with the card details or is able to provide these at the time of processing, that method is not enabled.

If a payment app defines a payment method as enabled then it MUST be able to process any payment request that lists that that payment method as supported and is formatted correctly according to the payment method specification for that payment method.

Payment mediators should only consider enabled payment methods when evaluating if a payment app is appropriate to process a given payment request.

Algorithms

The following algorithms must be implemented by all conforming payment apps:

Processing Payment Requests

The most important capability of a payment app is it's ability to process a payment request and return a valid payment response.

The steps for processing a payment request are given by the following algorithm. The algorithm takes a valid payment request (request) as input and returns a valid payment response (response).

  1. Let methods be an empty list.
  2. Let enabled methods be the list of payment method identifiers for the payment methods that are currently enabled in the app.
  3. Let candidate methods be the list of payment method identifiers listed as supported in request.
  4. If enabled methods is empty throw an exception.
  5. For each unique candidate payment method identifier in candidate methods
    1. If no identifier, that is an exact string match for candidate payment method identifier, is found in enabled methods, move onto the next item if there are any left.
    2. Append candidate payment method identifier to methods.
  6. If methods is empty throw an exception.
  7. Let selected payment method be the result of selecting a payment method with methods as input.
  8. Let response be the result of performing payment method specific processing with request and selected payment method as input.

Returning a list of enabled Payment Methods

In order for a payment mediator to know if it should consider passing a payment request to a payment app it must know which payment methods are enabled in that app.

The payment app MUST provide a mechanism for external components to get a list of enabled payment methods. The return value MUST be a set of unique payment method identifiers and the payment app MUST be capable of performing payment method specific processing for all payment methods identified by the identifiers in that set.

Extension Points

The following extension points are defined for implementation specific processing.

Selecting a Payment Method

A payment app should implement a mechanism for selecting a payment method which takes as input a list of payment method identifiers and returns a single payment method identifier. This mechanism MAY include user input, selection based on a custom algorithm or even configured defaults.

Performing Payment Method Specific Processing

A payment app that claims to have a particular payment method enabled must provide a mechanism for performing payment method specific processing for that payment method.

The input to this process will be a complete payment request and the payment method identifier of the payment method that should be used to process the request. The payment app SHOULD expect the request to contain any payment method data required to complete the processing of the request.

The specific behaviour of the payment app during this processing MAY include user interaction or communication with other systems or components. This will be defined, either explicitly or implicitly, in the appropriate payment method specification. The payment app MUST return a payment response that contains the appropriate payment method data for the payment method identified by the payment method identifier passed as input to the process.

Payment Mediator

The payment mediator sits between the payee's system and the payer's payment app(s) and performs a number of functions:

  1. It determines which payment apps can be used to fulfill a payment request given the payee's accepted payment methods.
  2. It helps the payer choose one (typically with explicit interaction or prior consent).
  3. It passes the payment request from the payee to the to the payer's selected payment app and passes the payment response from the payment app back to the payee.

Algorithms

The following algorithms must be implemented by all conforming payment mediators:

Filtering for capable Payment Apps

A payment mediator, upon receiving a payment request must compare the set of payment methods supported by the payee (as defined in the payment request) with the set of payment methods enabled in all available payment apps to which it has access and produce a list of payment apps that should be capable of processing the request.

The steps for getting a list of capable payment apps are given by the following algorithm. The algorithm takes a valid payment request (request) and the set of payment apps to which it is able to pass the payment request (apps) as input and returns a set of payment method identifiers.

There are a number of issues open against the browser API which need to be resolved to come to a conclusion on the correct algorithm to use in matching payment method identifiers.

Extension Points

The following extension points are defined for implementation specific processing.

Selection of Payment App

Once the mediator has determined the set of payment apps that are able to process the payment request it must select one and pass the request to it.

The steps for selecting a payment app are implementation specific and MAY involve user interaction with the payer or may involve an algorithm that uses defaults and configuration data to make the selection.

The input to this process is an ordered list of payment apps and the output is a single payment app.

Passing the Payment Request to the Payment App

The payment mediator must have some mechanism of passing the payment request to the payment app that was selected following the steps for selecting a payment app.

The payment request MUST not be altered by the payment mediator.