[w3c/browser-payment-api] PROPOSAL: Payment Method Identifiers taking advantage of URL characteristics (#205)

The group has resolved to use absolute URLs as PMIs. We should consider taking advantage of some of the additional characteristics of URLs then rather than continuing to match them purely as strings.

Parsing URLs is a simple process and is well-defined in [RFC 3986](https://tools.ietf.org/html/rfc3986). Rather than allowing the use of ANY URI we could also place some additional constraints on the URI as needed. (Example: Don't allow URNs, only URLs)

## Dereferencing

We are using absolute URLs so we should assume that some of these MAY be dereferenced to a resource such as a Payment Method Spec or similar informative document. However, we DO NOT want dereferencing of PMIs to be a run-time requirement (it should be used at design time only).

Therefor, "ownership" of a URL is important for the sake of dereferencing the URL but NOT for matching PMIs.

__Example:__ If the W3C publishes a payment method specification which associates the PMI "http://visa.com/payment-methods/cards" with the payment method "Basic Card Payment" then VISA controls the resource that is dereferenced by that PMI but not the content of the Payment Method Specification (published by the W3C).

## Matching

In the process of matching PMIs there may be a need to do some normalization of the URLs so that even if the PMIs are not an exact string match they will still be matched by the PMI matching algorithm.

One way to get two PMI's that can be matched but are still "owned" by different entities (i.e. the `host` portion of the PMI uses different domains) is to specify that the host is ignored during matching (and possibly the protocol portion too).

__Example:__ We can define normalization rules so that the following two PMIs will match:
* http://visa.com/payment-methods/credit-card
* https://w3.org/payment-methods/credit-card

This allows PMIs to be minted by an organisation that makes that PMI available for use in a payment method specification even if they don't publish that specification (e.g.: it is published by W3C or an industry association like EMVCo).

## /.well-known/

As we have already heard, it is difficult for organisations to lock down URLs that are under their primary domain and there is always a possibility that these will clash with existing web applications. 

Using Well-Known URLs would make it easier to define new URLs in a namespace dedicated for that purpose and reduce the possibility of clashes. It may also be extended in future to allow discovery of supported payment methods under a domain.

Well-Known URL's are defined in [RFC 5785](https://tools.ietf.org/html/rfc5785)

Using well-known URLs would simply extend the normalization rules such that the common prefix could also be ignored during matching.

This would allow us to define normalization rules so that the following PMIs all match:

* https://web-payments.org/payment-methods/card
* http://visa.com/.well-known/payment-methods/card
* http://www.mastercard.com/payment-methods/card

The WG should register the `/.well-known/payment-methods/` prefix and reference the PMI spec in that IANA registration

# Query parameters

One of the greatest challenges we have in defining this matching scheme is the verbosity of information that will be required in a payment request if a payee or payment app supports multiple (but not all) sub-classes of a payment method.

__Example:__ It is a challenge to say "I support all credit cards but not Visa", or "I support all debit cards but no credit cards".

One way to deal with this is to use query parameters and for each payment method spec to define the parameter names that it considers valid.

__Example:__ The card payment method specification could use the parameter `card-type` to indicate which specific cards it supports. So the following PMI would indicate support for the W3C published card payments specification but only for payments using visa, visa-debit, mastercard and unionpay-debit cards.

http://w3.org/payment-methods/card?card-type=[visa,visa-debit,mastercard,unionpay-debit]

_NOTE: Since there is no standard for passing arrays as query string params we can bikeshed the format, I like the JSON array encoding above._

# PROPOSAL

The following would solve the issue of "ownership" of the PMI URL and thus the resource it points to versus the ownership of the payment method specification itself. This opens up the possibility for publishing of payment method specs that extend existing specs with new PMIs (and possibly query parameters).

It also addresses the verbosity of PMI data in a payment request where granular specification of support is required.

Finally, it allows for some grouping semantics (if the matching of query string params is defined as below) that don't require the mediator to understand the specific semantics of the parameters themselves.

 1. Use well-known URLs and register `./well-known/payment-methods/` with IANA
 1. Include normalization rules in the matching algorithm that will ignore the host, protocol and either `/.well-known/payment-methods/` or just `/payment-methods/` path prefix if present.
 1. The matching algorithm should require that any query string parameters in the PMI are parsed and define logic for how these are used in the matching.

Proposed matching logic for query string parameters is to treat them as filters.
i.e. If not present then all possible values are supported.

Examples:

* http://example.com?param=[ABC] MATCHES http://example.com?param=[CDE]
* http://example.com?param=[ABC] MATCHES http://example.com?other-param=[1,2,3]
* http://example.com?param=[A] MATCHES http://example.com?param=[A,B,C]
* http://example.com MATCHES http://example.com?param=[A,B,C]
* http://example.com?param=[ABC] DOES NOT MATCH http://example.com?param=[DEF]




---
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/browser-payment-api/issues/205