Copyright © 2016 W3C® (MIT, ERCIM, Keio, Beihang). W3C liability, trademark and permissive document license rules apply.
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.
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.
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.
This section is non-normative.
There are a set of requirements that the payment method identifiers are designed to support:
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 section describes an approach to payment method identifiers using URLs.
Payment method identifiers are strings containing a URL. The string can be either an absolute URL or a relative 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.
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
.
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:
This section relies on several other underlying specifications.
This section is non-normative.
The following observations are made about this option:
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.
There is an open issue about whether payment method identifiers should resolve to a resource if they are URLs.
This section describes a way of expressing payment method identifiers using machine-readable URLs that may be aliased to developer-friendly short identifiers.
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).
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.
Payment method identifier URLs that resolve to content:
text/html
is requested, andapplication/ld+json
is requested.
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:
This section relies on several other underlying specifications.
This section is non-normative.
The following observations are made about this option:
This section describes an approach to payment method identifiers using strings that might be reverse domain names.
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.
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.
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.
A reverse domain name is defined by [REVERSEDOMAINS]. For example, com.example.somemethod
.
This section is non-normative.
The following observations are made about this option:
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 extensbility 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.