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.

Requirements for identifiers

There are a set of requirements that the payment method identifiers are designed to support:

  1. It must be possible for the Working Group to mint a payment method identifier for any payment method.
  2. It must be possible for anyone to mint a payment method identifier for a payment method under their control.
  3. It should be possible to use a standard short string to identify common payment methods.
  4. It must be possible for someone minting a non-standard identifier to make it globally unique in a cost-effective manner.

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.

This document currently specifies multiple alternate options for payment method identifiers. The Working Group has not yet selected an approach. The chosen approach might be one documented in this specification or another as yet undocumented proposal.

Option 1a

This section describes an approach to payment method identifiers using URLs.

Identifier format

Payment method identifiers are strings containing a URL. The string can be either an absolute URL or a relative URL.

Base URL

If the string is a relative URL then the base URL used by the URL parser is https://www.example.com/to-be-determined/.

The base URL needs to be determined and specified here. The base URL should be from a domain that the Working Group controls.

Short identifiers

Since payment method identifiers can be relative URLs, simple short strings can be used as identifiers and they will be parsed using the base URL.

For example, the string visa would be parsed into the URL https://www.example.com/to-be-determined/visa.

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:

Dependencies

This section relies on several other underlying specifications.

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

Discussion topics

The following observations are made about this option:

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

Option 1b

This section describes a way of expressing payment method identifiers using machine-readable URLs that may be aliased to developer-friendly short identifiers.

Identifier format

Payment method identifiers are absolute URLs that may optionally be aliased using short identifiers. For example, https://visa.com/payment-methods/VisaDebit (URL) or VisaDebit (short identifier).

Short Identifier Registry

A mapping file establishing short identifiers to payment method identifier URLs can be found at https://w3.org/registries/web-payments/v1. To reduce the load on fetching this file, it is encouraged that applications hard code the mappings.

Any short identifier registry that is not re-parsed every time will require a message version identifier to be embedded in the messages that use the short identifiers. The assumption here is that there is some versioning mechanism that is used by payment messages such that the payment apps and merchants know how to process short identifiers.

The format of the document located at the short identifier registry URL above still needs to be determined. Options include a plain JSON document or a JSON-LD document. The mappings would be as simple as: "VisaDebit": "https://visa.com/payment-methods/VisaDebit".

It is assumed that once the short identifier registry file is created, it is never updated. The Working Group may periodically release v2, v3, etc. registry files.

Content at Payment Method Identifier URLs

Payment method identifier URLs that resolve to content:

  1. MUST be served over HTTPS,
  2. SHOULD support HTTP Content Negotiation,
  3. SHOULD provide a human-readable document that describes the payment method when text/html is requested, and
  4. SHOULD provide a machine-readable document that describes the payment method when application/ld+json is requested.

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:

Dependencies

This section relies on several other underlying specifications.

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

Discussion topics

The following observations are made about this option:

Option 2

This section describes an approach to payment method identifiers using strings that might be reverse domain names.

Identifier format

Payment method identifiers are strings. The strings can contain any characters.

Payment method identifiers that are not created by the Working Group MUST be reverse domain name strings with at least one U+002E FULL STOP character. They SHOULD be based on domain names controlled by the creator.

It is RECOMMENDED that payment methods use simple lower-case ASCII identifier strings.

Short identifiers

Payment method identifiers that do not contain any U+002E FULL STOP characters MAY be created by the Working Group. These identifiers MAY be aliases for reverse domain name identifiers that do contain U+002E FULL STOP characters. If this is the case then implementations MUST process the identifier as if the reverse domain name form had been provided.

Any registration mechanism must allow a payment app to be registered with multiple aliases representing the same payment method identifier.

Identifier equivalence

Payment method identifier strings are compared using case-sensitive matching.

If a short identifier containing no U+002E FULL STOP characters is an alias for a reverse domain name identifier then the reverse domain name identifier should be used in any comparison.

Dependencies

A reverse domain name is defined by [[REVERSE-DOMAINS]]. For example, com.example.somemethod.

Discussion topics

The following observations are made about this option:

Issues

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

Should the format of the identifiers be URLs (e.g., http://example.com/paymentmethod) or reverse host name (e.g., com.example.paymentmethod) or some other extensible syntax?

If the identifier is a URL, should there be a resource that can be fetched from the URL?

Is there a need to describe the payment method at the URL or provide some other information?

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.