Payment Method Identifiers

The Payment Request API [[!PAYMENT-REQUEST-API]] requires that merchants supply a list of identifiers for supported payment methods. This document defines those identifier strings and how they are created.

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.

Introduction

One of the principles of the PaymentRequest API is that merchants must know how to accept payments from the payment methods that they claim to support. This allows the API to abstract away the details of specific payment methods and to add new ones over time without changing the API specification.

As part of the paymentRequest() call, the web page provides an array of strings that identify the supported payment methods. This document defines those strings.

Dependencies

This specification relies on several other underlying specifications.

URL: The terms URL, absolute URL, base URL, URL parser, and URL equivalence are defined by [[!url-1-20141209]] (or the editor's draft).

Payment Method Identifier

The Payment Method Identifier is a string that uniquely identifies a payment method that a user can use to complete a transaction. For example, Visa, MasterCard, and American Express are payment methods used in some countries.

Identifier format

Payment method identifiers are strings containing a URL. The string MUST be an absolute URL.

Identifier equivalence

When the PaymentRequest API is invoked, the web page provides a list of identifiers for supported payment methods. The user agent must compare these identifiers to those available to the user and use this to filter what the user can select. To determine whether two identifiers match, perform the following test:

Let A be the first payment method identifier string and let B be the second payment method identifier string.
Let urlA be the result from the URL parser when parsing A with no base URL.
Let urlB be the result from the URL parser when parsing B with no base URL
The identifiers match if urlA equals urlB using the URL equivalence test (i.e. the test returns true).

Issues

The following issues are tracking aspects of the payment method identifier specification:

Should there be well-known identifiers that are simple strings defined in the spec that don't conform to the distributed extensibility syntax that are used for common payment methods?

A registration mechanism may exist to install the code for new payment methods into the user agent. This process would add support for a new payment method to the user agent. This mechanism should be defined in a separate specification.

There is an initial outline making a proposal.

There is an open issue about whether payment method identifiers should resolve to a resource if they are URLs.