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. The current document describes a set of technologies —the Payment Request Architecture— that, together, provide merchants with a consistent way to request payment information from the user, aided by a user agent.

The focus of the Payment Request Architecture is to provide an abstract interface between a web page and a Payment App to facilitate a payment transaction. This is expected to streamline checkout and help reduce shopping cart abandonment, as well as make it easier to use new payment methods on the Web. This document does not describe a complete architecture for end-to-end payments on the Web.

This document does not address the full set of deliverables of the Web Payments Working Group.

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 report published previously by the Web Platform Incubator Community Group and A Payments Initiation Architecture for the Web developed within the Web Payments Working Group, and a blog post on the Working Group's work.

Overview of Anticipated User Experience

This (imperfect) overview of the anticipated user experience will help explain the architecture:


The following are key components of the Payment Request Architecture. These components would normally sit between the Payment Service Providers (PSPs) of the payer and payee. Different implementations of this architecture may result in components running on entirely different physical systems communicating over network boundaries or, in the other extreme, the same physical system assuming the role of a number of components with communication simply crossing process boundaries. For some payment schemes such as Bitcoin, the components communicate directly into the scheme's infrastructure.

Payment Apps

A Payment App is software used to pay. Banks, merchants, mobile operators, and anyone else who wants to will make these available. User agents are also likely to act as basic payment apps, storing some information on behalf of the user, as they already do today with passwords. We expect 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 standard API, such as strong user authentication, loyalty program integration, back-channel communications with the merchant for fraud analytics, and so on.

Payment apps should be able to run on desktops, mobile devices, televisions and other devices and operating systems. The execution environment for the Payment App is called the "Payment App Host." The Payment App Host may be tightly integrated with other components such as the Payment Mediator or may be one or more separate systems hosting individual Payment Apps or a combination of these.

As part of facilitating payment, 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., 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, interacts with the payer and payee, and communicates with third-party services will be determined by the implementer who provides the Payment App Host, as an execution environment for the app, and the Payment Mediator, that mediates all interactions between the Payment App and other components.

When a user registers a new payment instrument, how is that payment instrument shared between different browser brands? For example, if I register a Visa debit card issued by my bank in Google Chrome on my laptop, when I go to purchase something using my mobile phone, is that same debit card available to me via my Firefox web browser (assuming I've authenticated in some way with both browsers)?

Payment Methods

Each payment app will support one or more payment methods. A payment method is a system and set of rules for payments. We are designing the API to support the broadest possible array of payment methods. When a merchant accepts a given payment method, the assumption is that the merchant will know how to process the 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 to determine which payment methods to offer the user. Payment Method Identifiers will support distributed extensibility, meaning that there does not need to be a central machine-readable registry to discover or register payment methods.

The information required to use a Payment Method is called Payment Method Data. For a given payment method within a payment app, a user may have multiple instances of payment method data. Examples: a personal credit card (PAN, expiration data, CVV) and a business credit card, or multiple Bitcoin accounts.

Payment Mediators

The Payment Mediator fulfills a number of roles:

We expect that user agents will primarily act as payment mediators in this architecture.


The Payment Request Architecture organizes the above concepts into several component specifications so that they can be discussed and moved forward independently. The Payment Method Identifiers specification is the only common dependency. The following diagram shows the references between different specifications that describe the Payment Request Architecture. The arrows show normative references pointing from the referring document to the referenced document.

Relationship among different specifications in the Payment Request system

Payment Method Identifiers

The Payment Method Identifiers [[METHOD-IDENTIFIERS]] specification defines the format of Payment Method Identifiers.

If we choose to support well-known short strings for payment methods then we will need to determine where to define them. We may choose to define these well-known strings in a formal specification.

Payment Request API

The Payment Request API [[PAYMENT-REQUEST-API]] specification defines the API that makes a user agent the conduit for messages exchanged between web pages (or applications) and payment apps. The web page supplies a list of payment methods accepted by the merchant. The Payment Mediator matches those against payment methods supported by the user’s registered Payment Apps.

One principle of the Payment Request system is that when a merchant web site declares that it accepts a given payment method then it must know how to process the resulting response.

Payment Method Specifications

The Payment Request API specification has no intrinsic knowledge of the payment methods available. When a transaction is enacted by the user through the API a JSON object containing the relevant information necessary to process the transaction is returned. The format of this "message" is defined specifically for the payment method and might be private to that method.

We expect some message definitions to be shared amongst different payment apps. One example is the [[BASIC-CARD-PAYMENTS]], which defines a payment method identifier, method-specific request data, and method-specific response data for a basic card payment method. We expect this specification to be a model for other payment method specifications.

Payment App Registration Specifications

There is an open question within the working group about what registration scenarios should be supported by specifications from the group. See the Payment App Registration explainer and registration scenarios.


It has been suggested that all Web Payments specifications should use common terminology. There is a Web Payments Interest Group glossary that contains common terminology that could be integrated into this specification and automatically kept in sync via ReSpec's dynamic terminology import feature.
Payment Method
A way of paying. A system and set of rules for payments. A payment app may support one or more payment methods. Examples: cleartext-visa, tokenized-mastercard, (a fictitious payment service).
Payment Method Identifier
A way to identify a payment method. The payment mediator compares payment method identifiers to determine which payment methods to offer the user.
Payment App
A piece of software that enables a payer to make payments. A payment app may support one or more payment methods.
Payment Mediator
Software that matches payee-accepted payment methods and user-registered payment methods, and offers a choice to the user for selection.
Payment Method Data
The data describing an instance of a payment method. For example, for the cleartext-visa payment method this might be the card primary account number (PAN), expiry date, and CVV.

Relationship to Previous Concepts

This architecture uses concepts like "payment app" because the Working Group has found it challenging to adopt the "digital wallet" metaphor for several reasons:

There is not a one-to-one mapping from the previous concepts to the current ones, as the modeling is fundamentally different. Here is how previous and current concepts relate:

Current Previous Short definition
Payment App Digital Wallet, Payment Instrument An application, registered by the payer, that supports processing payment requests and returning payment responses for one or more payment methods.
Payment Method Payment Scheme A system and set of rules for payments.
Payment Mediator Digital Wallet, Payment Instrument A piece of software that coordinates messages between sellers and Payment apps.