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.

1. Introduction

This section is non-normative.

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.

2. Requirements for identifiers

This section is non-normative.

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

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

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

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:

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:

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:

  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.

5.4 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:

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:

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:

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.

B. References

B.1 Normative references

[PAYMENTREQUESTAPI]
Adrian Bateman; Zach Koch; Richard Barnes. Payment Request API. W3C Editor's Draft. URL: paymentrequest.html
[url-1-20141209]
Anne van Kesteren; Sam Ruby. W3C. URL. 9 December 2014. W3C Working Draft. URL: http://www.w3.org/TR/2014/WD-url-1-20141209/

B.2 Informative references

[REVERSEDOMAINS]
Reverse Domain Name Notation. URL: https://en.wikipedia.org/wiki/Reverse_domain_name_notation