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.

This topic is for the focus of the W3C Web Payments Working Group.

This document is an informal non-normative proposal.

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.

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 Payment Method Identifiers specification the only common dependency.

Relationship between different specifications in the Payment Request system

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

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

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.

Payment Transaction Message Specifications

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

There is an open issue highlighting that different card schemes have different manadatory requirements. This suggests that there might be a base credit card message format that supports the minimal set of required fields such as PAN and expiry date and other derived message formats based on the this that adds other fields such as start date.

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.

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.
Payment App
A piece of software that enables a payer to make payments. A payment app will one or more payment methods.
Payment Method Data
The data describing an instance of a payment method. For example, for the 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.