Payment Method Identifiers

Abstract

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

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

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.

This document was published by the Web Payments Working Group as a First Public Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-payments-wg@w3.org (subscribe, archives). All comments are welcome.

Publication as a First Public Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 September 2015 W3C Process Document.

4. Option 1a

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

4.1 Identifier format

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

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

Editor's Note

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

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

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

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

4.5 Discussion topics

This section is non-normative.

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

Issue 46: Should a payment app identifier (URL) or a payment method identifier (URL) resolve to a machine readable resource that describes it?

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

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

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

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

Issue

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.

Issue

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

Issue

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.

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

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

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

5.6 Discussion topics

This section is non-normative.

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

6. Option 2

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

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

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

Note

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

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

6.4 Dependencies

A reverse domain name is defined by [REVERSEDOMAINS]. For example, com.example.somemethod.

6.5 Discussion topics

This section is non-normative.

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.

A. Issues

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

Issue 11: What is the format for payment method identifiers for distributed extensibility

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?

Issue 10: Should well-known identifiers be used for ubiquitous payment methods

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

Issue 12: Write-up initial proposal for payment app registration spec

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.

Payment Method Identifiers

W3C First Public Working Draft 21 April 2016

Abstract

Status of This Document

1. Introduction

2. Requirements for identifiers

3. Payment Method Identifier

4. Option 1a

4.1 Identifier format

4.1.1 Base URL

4.2 Short identifiers

4.3 Identifier equivalence

4.4 Dependencies

4.5 Discussion topics

5. Option 1b

5.1 Identifier format

5.2 Short Identifier Registry

5.3 Content at Payment Method Identifier URLs

5.4 Identifier Equivalence

5.5 Dependencies

5.6 Discussion topics

6. Option 2

6.1 Identifier format

6.2 Short identifiers

6.3 Identifier equivalence

6.4 Dependencies

6.5 Discussion topics

A. Issues

B. References

B.1 Normative references

B.2 Informative references