diff --git a/specs/architecture.html b/specs/architecture.html index 36de3a7d..e96088f0 100644 --- a/specs/architecture.html +++ b/specs/architecture.html @@ -1,7 +1,7 @@ - Payment Request Architecture + Payment Request API Architecture @@ -54,6 +54,16 @@ ] , status: "ED" } + "BASICCARDPAYMENTS": { + title: "Basic Card Payment" + , href: "basic-card-payment.html" + , authors: [ + "Adrian Bateman" + , "Zach Koch" + , "Richard Barnes" + ] + , status: "ED" + } } }; @@ -63,12 +73,22 @@
-

- The Payment Request architecture is designed to separate different concerns of the - Payment Request system into different specifications so that they can be discussed and moved - forward independently. This document describes the architecture and explains what different - specifications may be created and how the relate to each other. +

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 browser or other 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.

@@ -79,160 +99,254 @@ 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. + 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:

+ + +
-

Introduction

-

- The goal of the Payment Request system is for a user agent to provide an abstract interface - between a web page and a payment app to facilitate a payment transaction, for example - between a merchant and a customer. A payment app allows the user to process a transaction - with a payment method (though a payment app may support multiple payment methods). - A user agent may support many different payment methods. -

-

- The Payment Request architecture is designed to separate different concerns into - different specifications so that they can be discussed and moved forward independently. - The common component of each of the elements in the architecture is the payment method - identifier. Payment method identifiers are defined in a separate document to which all other - documents refer. -

+

Components

+ +

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

+
+ +
+

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 browsers will primarily act as payment mediators in this architecture.

+
-

Architecture

-

- The following diagram shows the references between different specifications that describe - the Payment Request system. The arrows show normative references pointing from the referring - document to the referenced document. -

-

- The goal of this architecture is to minimise cross-references to allow different documents - to proceed at their own pace. The proposal makes the +

Specifications

+ +

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 the only - common dependency. + 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 between different specifications in the Payment Request system
+
Relationship among different specifications in the Payment Request system

-

- The following sections describe specifications that define the Payment Request architecture. -

-

Payment Method Identifiers

+

Payment Method Identifiers

The Payment Method Identifiers [[METHODIDENTIFIERS]] specification defines the format of - payment instrument identifiers. This document is a dependency for all other specifications - in the architecture.

+ 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

+

Payment Request API

The Payment Request API [[PAYMENTREQUESTAPI]] specification defines the API that makes a - user agent the conduit for messages exchanged between web pages and payment apps. - The web page supplies a list of payment methods accepted by the merchant. The user agent - will match those against payment methods supported by the user’s registered payment apps. + 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 response that - gets returned when the user accepts the request. -

-
- -
-

Payment Method Registration Specifications

-
- There is an open question within the working group about what registration scenarios - should be supported by specifications from the group. -
-

- The architecture highlights two possibilities for registration scenario. Other - scenarios could be supported. -

-

- One scenario is registering a new payment app. For example, this would allow bobspay.com - to install an app into the user agent that would support transactions through the Payment - Request API using the bobspay.com Payment Method Identifier. -

-

- Another scenario is that of registering specific Payment Method Data within a payment - app. For example, this would allow a user logged in to the Alice Bank web site to register - their Visa credit card with the Visa payment app. + that it accepts a given payment method then it must know how to process the resulting + response.

-

Payment Transaction Message Specifications

+

Payment Method Specifications

- The abstract Payment Request API specification has no intrinsic knowledge of the payment + 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. However, we expect some message definitions to be shared amongst different - payment apps. For example, we expect multiple different payment apps to support returning - credit card PANs and they should all do so using the same field names. + to that method.

+ +

We expect some message definitions to be shared amongst different + payment apps. One example is the [[BASICCARDPAYMENTS]], 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 Method Identifier Registry

-

- 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. - For convenience, we may choose to host a Wiki page that allows developers of payment methods - to publish links to their documentation including the format of payment request messages. - The architecture diagram indicates this Wiki. -

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

Glossary

-
- The definitions in this section are derived from the - working group wiki architecture page. -
-

- The following terms are used in this document. -

Payment Method
-
- A way of paying. A system and set of rules for payments. A payment app may support one or - more payment methods. For example, Visa, Mastercard, American Express, bobspay.com are - payment methods. +
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, bobspay.com (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 will one or more + A piece of software that enables a payer to make payments. A payment app may support one or more payment methods.
-
Payment Method Data
+
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 Visa payment + 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. -
- Payment Method Data is unique to this spec and isn't currently defined in the Web Payments architecture wiki. -
-
+ + +

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:

+ + + + + + + + + + + + + + + + + + + + + + +
CurrentPreviousShort definition
Payment AppDigital Wallet, Payment Instrument A piece of software to pay
Payment MethodPayment SchemeA system and set of rules for payments.
Payment MediatorDigital Wallet, Payment InstrumentA piece of software that coordinates messages between Web apps and Payment apps
+
- \ No newline at end of file +