Latest editor’s draft:https://w3c.github.io/webpayments/architecture/index.htmlEditor:Adrian Hope-Bailie (Ripple)Version Controller: Github repository issues
This document is licensed under a Creative Commons Attribution 3.0 License.
The assignment of the Web Payments Working Group will be to create payments easier and safer on the Web.
The group is also chartered to come up with numerous technologies. This document describes an architecture and a pair of functions within that structure which, together, ease the group’s assignment.
This blatantly refers to components by their own role, recognizing that different implementations might come in numerous functions being embraced by one system component. No particulars are defined about the way the works of each role is going to probably be fulfilled beyond the interior calculations which every needs to implement. Specific interfaces might be clarified at length in accompanying documents define these functions have been employed inside those contexts.NOTE
This structure is centered on the connections between a payer and payee on the Web and will not pay for the components or architecture needed for the entire endtoend payment procedure.
Status of This Document
This document is draft of a potential specification. It’s no official status of any sort and doesn’t represent the support or consensus of almost any standards organization.
The working group maintains a list of all bug reports that the group has not yet addressed. This draft highlights some of those impending issues which remain to be discussed in the working group. No decision was taken on the outcome of these issues including whether or not they are valid. Pull requests with proposed specification text for exceptional problems are strongly encouraged.
This specification was derived from A Payments Initiation Architecture for the Web.
Table of Contents
- 1.Design Decisions
- 4.Payment Request Flow
- 5.Payment Methods
- 6.1Payment App
- 6.2Payment Mediator
1. Design Decisions
1.1 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 estabilsh a bi-directional channel of communcation 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.
1.2 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 conencting the requesting payee system with an appropriate payer payment app.
In this document we use the following terms with the implied definition as stated below:PayerA 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.PayeeA 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 RequestA 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 conatin all of the payment method data required for each payment methodidentified in it’s set of supported payment methods.Payment ResponseA 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 AppA payment app is a component that fulfills the conformance criteria specified for a payment app in this specification.Payment MediatorA payment mediator is a component that fulfills the conformance criteria specified for a payment mediator in this specification.Payment MethodA 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 DataPayment requests and payment responses have a limited set of data elements that are common to all payments, irresepective 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 SpecificationA 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 IdentifiersPayment Method Identfiers are defined in [METHOD-IDENTIFIERS]
As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.
The key words MAY, MUST, and SHOULD are to be interpreted as described in [RFC2119].
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.
4. 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 singlepayment 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.
5. 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 perosn or entity can define a new payment methodas long as they publish a payment method specification that defines:
- How a payment app should process a payment request.
- What payment method data is expected to be included in the request.
- What payment method data is expected to be included in the response.
- What payment method identifiers identify this payment method.
The following are the key roles within this architecture.
6.1 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.
6.1.1 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.
The following algorithms must be implemented by all conforming payment apps:
184.108.40.206 Processing Payment Requests
- Let methods be an empty list.
- Let enabled methods be the list of payment method identifiers for the payment methods that are currently enabled in the app.
- Let candidate methods be the list of payment method identifiers listed as supported in request.
- If enabled methods is empty throw an exception.
- For each unique candidate payment method identifier in candidate methods
- 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.
- Append candidate payment method identifier to methods.
- If methods is empty throw an exception.
- Let selected payment method be the result of selecting a payment method with methods as input.
- Let response be the result of performing payment method specific processing with request and selected payment method as input.
220.127.116.11 Returning a list of enabled Payment Methods
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.
6.1.3 Extension Points
The following extension points are defined for implemntation specific processing.
18.104.22.168 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.
22.214.171.124 Performing Payment Method Specific Processing
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 identifed by the payment method identifier passed as input to the process.
6.2 Payment Mediator
The payment mediator sits between the payee’s system and the payer’s payment app(s) and performs a number of functions:
- It determines which payment apps can be used to fulfill a payment request given the payee’s accepted payment methods.
- It helps the payer choose one (typically with explicit interaction or prior consent).
- 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.
The following algorithms must be implemented by all conforming payment mediators:
126.96.36.199 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.ISSUE: Determine the correct matching algorithm for 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 mathcing payment method identifiers.
6.2.2 Extension Points
The following extension points are defined for implemntation specific processing.
188.8.131.52 Selection of Payment App
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.
184.108.40.206 Passing the Payment Request to the Payment App
A.1 Normative references
[METHOD-IDENTIFIERS]Payment Method Identifiers. Adrian Bateman; Zach Koch; Richard Barnes; Roy McElmurray.W3C Working Draft. URL: https://w3c.github.io/browser-payment-api/specs/method-identifiers.html[RFC2119]Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
Source credit : https://w3c.github.io/webpayments/proposals/architecture/#definitions