Suggest two alternative payment method identifier proposals

[adrianba]

As discussed at the last telcon, we need concrete proposals for how to specify payment method identifiers.

This pull request adds two different options for specifying payment method identifiers to the payment method identifier spec in order to advance discussion on issues #10 and #11.

This pull request is intended to provide examples of one way to propose an identifier scheme. It is also intended to offer spec text that we might include in a FPWD to more clearly explain the scope of the document. It is not intended to indicate that the group has to choose from only these options (and the language says this explicitly).

With that said, at Microsoft we prefer option 2 of the two presented.

You can read the specification with the proposed changes applied here.

[zkoch]

@adrianba, is expectation that people with other proposals would edit this doc by adding more options (e.g. option 3, etc)?

[mattsaxon]

@adrianba thanks for the write up. Since you are proposing 2, I'd like to highlight a few benefits I perceive in option 1, perhaps they can be delivered in option 2 also?

1. Equivalence of payment identifiers could perhaps be modelled via HTTP redirects, so for example http://www.w3c.org/card/visa could be shown to be equivalent to http://www.visa.com/card via an HTTP 3xx response code.
2. This same approach could be used where companies change brand names, a frequent occurrence in payments as we've seen from the Switch/Maestro investigations we've done.
3. The ability to have a resource at the URI seem to me to be so useful, that I believe it trumps the issue about inappropriate caching of XML namespaces. I think being able to find the documentation for a given payment method at a URI is key to the ecosystem evolving.

[ianbjacobs]

@adrianba,

Thanks very much for writing these up. I like option 1 and have in my head that one could usefully dereference the payment method URI to get the spec that defines the method-specific data (request and response) as well as any other information about the identifier.

I understand there are disagreements about "why people use URIs." I disagree with this statement: "The intent of a URL is to load or locate a resource and may only be done sometimes with this proposal." I would be more comfortable with: "For many people, when they see a URL the expect to be able to dereference it, which may lead to confusion as this specification would not require that the URLs be dereferenceable."

Regarding: "Experience with XML namespaces suggests that optional 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."

I think the spec could say something like this:

• GOOD PRACTICE: Offer human-readable payment method specifications when people dereference these URIs.
• Conforming user agents SHOULD NOT automatically dereference these URIs because this specification suggests that the identified resources are human readable documents.

@mattsaxon,

I would not want an equivalence test in general to require a network request.

[mattsaxon]

@ianbjacobs fair point to it 'requiring' this, and I appreciate that caching has its downsides too, but I do see value in modelling this in documentation if not in execution architecture.

[dlongley]

@ianbjacobs,

Conforming user agents SHOULD NOT automatically dereference these URIs because this specification suggests that the identified resources are human readable documents.

I don't understand this reasoning. What does the resources being human readable have to do with whether or not they should be dereferenced?

[ianbjacobs]

@dlongley,

My reasoning was this:

• If we tell people that good practice is putting a human readable payment method spec at the end of these URIs (and that's all we say) then we should let user agents know that they are not likely to find machine-readable information there. So they should not automatically dereference these URIs since they are unlikely to find anything useful there to process.

Ian

[dlongley]

@ianbjacobs,

A human readable resource may also contain machine readable information (so I consider the proposed language to be a non-sequitor). It also seems like "SHOULD NOT" is the wrong language here -- and that we should instead be informing user agents that there is no expectation of machine readable information at these resources. I don't see any reason to tell user agents that they shouldn't automatically dereference these URIs -- it may become a best practice to also include machine readable information at them (indeed, I think that should be the case).

Perhaps we should say that a user agent may not automatically dereference the URIs because there is no expectation of machine readable information?

[ianbjacobs]

@dlongley,
You wrote: "A human readable resource may also contain machine readable information"

Yes, that's true, but for the moment we are not recommending that.

"and that we should instead be informing user agents that there is no expectation of machine readable information at these resources."

Yes.

"I don't see any reason to tell user agents that they shouldn't automatically dereference these URIs -- it may become a best practice to also include machine readable information at them (indeed, I think that should be the case)."

What would you put there?

"Perhaps we should say that a user agent may not automatically dereference the URIs because there is no expectation of machine readable information?"

I think "MAY NOT" is not the right RFC2119 language. I don't mind saying somethign like:

"We do not recommend that user agents automatically dereference these URIs because there is currently no general expectation that machine readable information will be retrieved."

Ian

Ian

[zkoch]

I think I'm also generally in favor of URLs. I want to clarify what is being proposed in option 1. Would the idea be that every payment method should live at tobedetermined.com? Or just the ones that we standardize up front? For example, let's say my support payment methods were: Visa, Mastercard, and BobPay.xyz (a proprietary, closed-loop system). Would the final array look like:

['https://www.bobpay.xyz', 'https://www.tobedetermined.com/visa', 'https://www.tobedetermined.com/mastercard']

Which could then be made shorter with:

['bobpay.xyz', 'Visa', 'Mastercard']

Or is the idea that even Bobpay would have to live behind tobedetermined.com, such as:

[`https://www.tobedetermined.com/bobpay.xyz', '...', '...']

Seems like it's the former, but I want to clarify.

[ianbjacobs]

@zkoch,

My understanding (and strong preference) is the former.

Ian

[dlongley]

@ianbjacobs,

"We do not recommend that user agents automatically dereference these URIs because there is currently no general expectation that machine readable information will be retrieved."

I think that's ok, but seems sub-optimal. Wouldn't it be better to say it can be done but you might not get anything useful out of it? For example:

"A user agent MAY automatically dereference these URIs, but there is no general expectation that machine readable information will be retrieved."

I think saying that we don't recommend it can be taken as a suggestion that they don't do it vs. a statement that they are free to do what they want, it's not a requirement, and they might not find anything easily consumable on the other end.

[ianbjacobs]

@dlongley,

I think that approach sets the wrong tone. The tone here should be avoidance. We are not forbidding and they may find something useful. But the expectation is that they won't.

You can ALWAYS try to dereference a URI, so saying that they "may" here is unnecessary as well.

(Adding one clarification: I am only mentioning all of this in response to the concern that software developers might unwittingly do something...I want to help them avoid that problem if we conclude it's a real issue.)

Ian

[adrianba]

is expectation that people with other proposals would edit this doc by adding more options (e.g. option 3, etc)?

Yes, we could add other options or refine the ones there. I'm not necessarily wedded to the language. I'd also like to highlight (probably more strongly than this PR) different issues and opinions people in the group have. I'd like to see proponents for option 1 propose changes to remove my bias against it. 😄

Since you are proposing 2, I'd like to highlight a few benefits I perceive in option 1, perhaps they can be delivered in option 2 also?

Please propose how to change the language in the pull request to include your views in the advantages/disadvantages notes if you want. I think needing to dereference a URL in order to do an equivalence check would be a huge disadvantage, personally.

[mattsaxon]

@zkoch I think the former also, but I would like to explore what that means if visa want to change their scheme, hence my suggestion of visa also being able to be specified as https://visa.com/card. I realise don't have a good answer here as Ian pointed out with my redirect suggestion!

[adrianba]

Would the idea be that every payment method should live at tobedetermined.com? Or just the ones that we standardize up front?

The idea is only payment methods the working group defines (or approves) should be relative to the base URL. This is because they can't de done in a distributed way.

This would mean you could use ['//bobpay.xyz', 'Visa', 'Mastercard'] or perhaps better ['//bobpay.xyz/v1', 'Visa', 'Mastercard'] . Note the // to make the URL a scheme-relative URL.

[adrianba]

I think the former also, but I would like to explore what that means if visa want to change their scheme, hence my suggestion of visa also being able to be specified as https://visa.com/card. I realise don't have a good answer here as Ian pointed out with my redirect suggestion!

It is possible for multiple payment method identifiers to be synonyms. Option 2 calls this out but it applies equally to Option 1. It is important that during registration all the synonyms for a payment method are declared so that the equivalence check can be done authoritatively.

If the scheme changes resulting in different messaging then a new identifier is required.

[adrianba]

One of the problems with option 1 if we expect to dereference the URLs is that somebody has to provide (probably a huge amount of) bandwidth for hosting the base URL and operating a service that hosts (or redirects to) the content.

[mattsaxon]

ok, that works (as you say for both options), then the option 1 redirect would just be for documentation purposes, not at execution time.

[mattsaxon]

I don't think we should be dereference the URL at execution time, this should be for design time documentation IMO.

[ianbjacobs]

@adrianba,

I acknowledge the cost, but people make a business decision to host useful resources.

Here is my thinking in a nutshell:

• We need identifiers.
• We also need documentation of the shape of payment request and payment response data for
  different payment methods.
• People who are using the identifiers need that documentation to use the payment method.
• Therefore, the identifiers should be (good practice) URIs to documentation on how to use
  the payment method associated with the identifier.

Otherwise, people will have to hunt around for the payment method specs.

If one has multiple identifiers that are specified by the same payment method spec,
then those can all (HTTP) redirect to that spec.

@adrianba makes an interesting point about synonyms. My first reaction is that the payment identifier spec should not define synonym semantics. (I prefer simpler equivalence semantics there, as Adrian has proposed) Adrian mentions a "synonym" functionality at registration time, which I had not thought of. If we push that computation to the payment app, there may still be a way to increase interop among payment apps by encouraging people to define synonyms in payment method specs. I can
see the value of having a machine-readable version of synonyms consumable by payment apps.

Ian

[adrianba]

Here is my thinking in a nutshell:

• We need identifiers.
• We also need documentation of the shape of payment request and payment response data for different payment methods.
• People who are using the identifiers need that documentation to use the payment method.
• Therefore, the identifiers should be (good practice) URIs to documentation on how to use the payment method associated with the identifier.

I don't think it follows that because developers need documentation then the identifiers that they use should point to the documentation. In fact, I think this is back-to-front. Developers will need to find the documentation in order to know if there is any payment method specific information needed on request, to know what the response message looks like, and to know what options are available for complete(). It seems simple to me that they can also find the payment method identifier from the same document and nobody is going to assume that the identifier must naturally be what's in the address bar of their browser while reading it.

[adrianba]

I don't think we should be dereference the URL at execution time, this should be for design time documentation IMO.

I don't think the complexities of URLs are worth it just to have a link to documentation.