PROPOSAL: Payment Method Identifiers taking advantage of URL characteristics

[adrianhopebailie]

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

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

[sideshowbarker]

Parsing URLs is a simple process and is well-defined in RFC 3986.

I think it’s not actually such a simple process, and if you want to have URL parsing that’s closer to being interoperable with how browsers actually parse URLs the spec to conform to is the current URL Standard.

[sideshowbarker]

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

As I’ve explained in multiple other comments so far, it would be a mistake to assume that the W3C will agree to host URLs for the WG for these resources. The WG instead should consider taking responsibility on its own for setting up a hosting plan for them that does not involve the W3C continuing to have to troubleshoot any issues or downtime related to them and that does not involve the W3C continuing to incur any (unexpected) costs of hosting them for dozens of years long after this WG has completed all its work and gone away.

[adrianhopebailie]

it would be a mistake to assume that the W3C will agree to host URLs for the WG for these resources

:+1: - this was just an example

[adamroach]

@adrianhopebailie --

...specify that the host is ignored during matching...

I don't think this is what we want.

The rationale behind using URLs for identifiers, as I understand it, is to allow for decentralized allocation of identifiers without an authoritative registry. This only works if the identifiers are scoped in some way to the entity performing the allocation. If we ignore the hosts during matching, then we will easily end up with different entities defining different mechanisms and assigning them IDs that match per your proposed rules.

[msporny]

-1 to the proposal (sorry, AdrianHB). I do think your proposal does provide a way of addressing this issue of large lists of PMIs in the messages, but I'd rather kick that particular can down the road by not creating a complex algorithm to do matching (yet). Let's deploy with the large lists of PMIs and see what feedback we get from the developer community. I think that many won't care as long as they don't have to generate the long lists (for example, they could use a payment library convenience function to generate the lists).

I think the correct order of operations is:

1. In version 1, don't do grouping, aliasing, or complex matching algorithms.
2. Gather data on all the different types of PMIs used in the system after v1 is deployed.
3. Deploy new PMIs for groupings that make the most sense (99% of the market always uses these 23 PMIs together).
4. In version 2, deploy aliases if people are still asking for them.

[msporny]

Big -1 for any use of /.well-known/, btw - having deployed some web payments stuff on top of /.well-known/, it always felt like a hack (there are better ways to do /.well-known/).

[adamroach]

@msporny --

Big -1 for any use of /.well-known/, btw - having deployed some web payments stuff on top of /.well-known/, it always felt like a hack (there are better ways to do /.well-known/).

Agreed with not using /.well-known/. The idea behind /.well-known/ is that you can, given (only) an application and a domain, access the resource at that domain that corresponds to the application. When you can pass full URLs around, it's much architecturally cleaner to pass full URLs around. This is true not just for payment apps, but in general.

[ianbjacobs]

-1 to /.well-known. I prefer that we not tell people how to organize their Web sites.

We have discussed a few key topics: extensibility, syntax, grouping, aliases, and dereferencing.

Here's my current understanding:

• Extensibility. Closed since we picked URLs
• Syntax. Mostly closed since we picked URLs, but we may say more if we include grouping/subclassing semantics.
• Dereferencing. I have not heard anyone say this is a MUST, therefore I suggest we postpone discussion of dereferencing until we have more experience. UPDATE: We discussed this on the 26 May call and apparently this issue of dereferencing is not as settled as I thought.
• Aliases. I hear only lukewarm support at this point (and some stronger opposition) so
  I suggest we not include short aliases at this time.

That leaves the matching algorithm. The matching algorithm's complexity will depend on whether we want grouping/subclassing semantics. If we don't, we can use well-known URL equivalence testing. If we do, we need to specify more.

Personally I think we should endeavor to include subclassing/grouping in V1. There are different degrees that we might strive to achieve:

1) Exclusion only. That would allow someone to say "I support Brand X but not sub-brand Y." That would address some use cases and could be addressed outside of syntax by having a new field in the paymentRequest() API which is "not accepted." The matching algorithm implemented by the browser would be more complex than simple URL
equivalence, but not a lot more complex.

2) Sub-brand matching. This would allow us to meet this use case: "Merchant accepts Brand (or sub-brand) X" while "User has Y, which is a sub-brand of X." There have been two proposals so far that endeavored to achieve that:

a) Matt's URL path hierarchy.
b) Adrian's query params (which MattS and I have also discussed).

I don't like (a) because I think it's brittle. I am not yet convinced by (b) and would like to hear more viewpoints.

Ian

[rsolomakhin]

Sounds like we can move forward with exact matches and continue thinking about subclassing and grouping.

[ianbjacobs]

I want to ruminate this week and next on a hybrid approach that gets us part of the way there simply, and allows for some experimentation. That's vague. :)

[adrianhopebailie]

Thanks for the feedback. I think there are aspects of this I will propose in a simpler proposal. Closing this one.

[sideshowbarker]

See the thread at https://twitter.com/stevenpemberton/status/737698895359250432 for another example of the kind of (sometimes baffling) problem that can be caused by baking in dereferencable URLs as IDs