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.

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:

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 using the base URL specified above.
Let urlB be the result from the URL parser when parsing B using the base URL specified above.
The identifiers match if urlA equals urlB using the URL equivalence test (i.e. the test returns true).

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:

This option satisfies requirement 1 because the Working Group can specify identifiers leading to URLs from domains that the Working Group controls.
This option satisfies requirement 2 because anybody can specify identifiers leading to URLs from domains that they control.
This option satisfies requirement 3 because the Working Group can specify common payment method identifiers as short string relative URLs. Since the Working Group is defining them, they can be relative to the Working Group defined base URL.
This option satisfies requirement 4 because it is within your control to create URLs from domains that you control that are globally unique.
Advantages:
- URLs are familiar and easily understood.
- URLs can easily be created in a distributed fashion.
- The parsed URL could be used as part of a discoverable registration mechanism. For example, a manifest resource could be located at the URL: a user agent could download the manifest whenever a merchant supports a method that the user agent doesn't recognised.
  
  However, registration is a comparatively rare operation compared to making a payment. If a user agent downloads manifests every time a site calls the API this could result in a tremendous amount of traffic.
  For example, if bobspay.com has a manifest file then lots of merchants might support this payment method. If there exist lots of users who never want to install the bobspay.com payment app but who visit sites that accept bobspay.com then there is going to be lots of traffic generated for the bobspay.com manifest.
Disadvantages:
- URLs are difficult to remember and developers often need to find a reference to copy and paste them from.
- Developers may find it confusing to us a URL if it isn't intended to point to a resource.
- Overloading the same string to mean an identifier in some cases and a resource location in others is undesirable. The intent of a URL is to load or locate a resource and may only be done sometimes with this proposal. A URL might mistakenly be crafted as an identifier but later lead to attempts to load it that weren't anticipated (by potentially large numbers of users).
- Experience with XML namespaces suggests that optionally downloading resources from identifiers tends to encourage user agents to hard code common identifiers for performance reasons potentially leading to a closed or unbalanced system.

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:

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

Identifier Equivalence

Let A be the first payment method identifier and let B be the second payment method identifier.
If A or B is listed in the Short Identifier Registry, replace the value with its corresponding absolute URL.
Let urlA be the result from the URL parser when parsing A.
Let urlB be the result from the URL parser when parsing B.
The identifiers match if urlA equals urlB using the URL equivalence test (i.e. the test returns true).

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:

This option satisfies all requirements that Option 1 satisfies.
Advantages over Option 1a:
- Relative URL and Base URL processing is avoided entirely while ensuring that short identifiers can be used.
- The Web Payments Working Group only has to maintain a short identifier mapping file, not a complete payment method identifier registry.
- Hard coding and/or aggressive caching of the short identifier mappings are encouraged as changes to the short identifiers are disallowed after every major release.
- Machine-readable information is encouraged to be published at payment method identifier URLs but is not required.
Disadvantages wrt. Option 1a:
- None

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:

This option satisfies requirement 1 because the Working Group can specify identifiers from reverse domains that the Working Group controls.
This option satisfies requirement 2 because anybody can specify identifiers from reverse domains that they control.
This option satisfies requirement 3 because the Working Group can specify common payment method identifiers as short strings that do not contain a U+002E FULL STOP character.
This option satisfies requirement 4 because it is within your control to create identifiers from domains that you control that are globally unique.
Advantages:
- Identifiers are relatively short strings even in the reverse domain case.
- It is straightforward to create new identifiers from a domain you control and there is no ambiguity about its use or purpose.
Disadvantages:
- There is no way to automatically dereference a payment method identifier from this option to a resource located at a URL.

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.

Introduction

Requirements for identifiers