diff --git a/specs/method-identifiers.html b/specs/method-identifiers.html index eedc310a..1d9962e9 100644 --- a/specs/method-identifiers.html +++ b/specs/method-identifiers.html @@ -89,15 +89,13 @@

Introduction

-
-

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. -
  2. It must be possible for anyone to mint a payment method identifier for a payment method under their control.
    3. -
  3. It should be possible to use a standard short string to identify common payment methods.
    4. -
  4. It must be possible for someone minting a non-standard identifier to make it globally unique in a cost-effective manner.
    5. -
+
+

Dependencies

+

This specification relies on several other underlying specifications.

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

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.

+

Payment method identifiers are strings containing a URL. The string MUST be an absolute URL.

Identifier equivalence

@@ -142,294 +115,34 @@

Identifier equivalence

  • 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.
    • +
  • Let urlA be the result from the URL parser when parsing A with + no base URL.
    • +
  • Let urlB be the result from the URL parser when parsing B with + no base URL
  • 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: -

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

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

+

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?

+
-
-

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.

+
-
-

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.

-
+
+

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

+