What semantics is needed for payment method specific data?

[ianbjacobs]

Pull request #133 (#133) relates to how payment method specific data is passed through the API.

A separate question is: what semantics is needed for this data (however it is supplied)?
We have several options (however the data is passed through the API):

1. Leave it undefined. Payment apps would have to figure out themselves
   what the data mean, possibly through other specifications. This would give
   merchants maximum flexibility to encode the information however they want,
   but we would decrease payment app interoperability.

2. Payment method identifiers are (the only) keys. One example in the FPWD
   suggests this is what is intended, but it's not formally defined that way in the spec.

3. We could specify some sort of expression language to increase interop. To illustrate what
   I mean (but not what I am proposing), one could imagine this sort of spec (where "PMI" is
   short for Payment Method Identifier):

   date :: = ( data key ":" value ) *
   data key ::= [, ] | "*"

(Apologies for poor BNF)

Which means you could do things like this:

pm1: { .... data here .... } /* Basic case */

• : someValue /* Applies to all payment methods /
  pm1, pm2, pm3 { someFlag: true } / One value shared by multiple payment methods */

This could be powerful from a developer perspective (more expressive, more terse) but
complicated for implementers (e.g., custom parsing of multi-PMI data keys). I'm not proposing
this approach because I believe it is overly complex for v1.

I believe we should support both of these goals:

• Support payment method specific data in the API
• Promote payment app interoperability (meaning: two apps supporting a given payment method
  can follow specifications and behave similarly).

Given how fundamental payment method identifiers are to the architecture (so they
will be widely supported and understood), and without additional experience, I am
personally fine with option 2 above. But if we choose that option, the spec needs
to include normative language.

Ian

[dlongley]

We should do something like option 3.

[dlongley]

To be clear, I don't think we should invent that new language, we should just reuse a technology that already does it for us and is a W3C Recommendation. It should be combined with Option 2 -- as an optional way to increase interop, and I believe we're already suggesting something like this in an issue marker under an extensibility section.

[ianbjacobs]

@dlongley,

My point in this issue is not to talk about extensibility, but to talk about the semantics we need to define.

When you say "reuse a technology that already does it for us" you haven't said anything about what behavior will be well-defined enough to enable interoperability.

Ian

[dlongley]

@ianbjacobs,

I'm saying that there are existing technologies that can indicate what the semantics of particular predicates are -- and entire vocabularies comprised of such predicates can be published and be machine readable. These vocabularies can be mixed and matched/reused within JSON data. This approach allows payment methods to reuse vocabulary terms defined by other payment methods -- and know what their meaning is.

I don't think we need to say what those particulars are, we just need to show how to take advantage of this technology via best practice documents or similar. We could show example payment method specifications that share common vocabulary terms that use this "expression language".

[ianbjacobs]

@dlongley,

"I don't think we need to say what those particulars are..."

That answers my immediate question. That suggests "option 1".

Ian

[dlongley]

@ianbjacobs,

That answers my immediate question. That suggests "option 1".

I think it's a little bit of Option 2 (we should be clear about what Payment Method Identifiers are) ... but I may be misunderstanding there. But, for the most part, yes, we don't have to actually say what the particulars are. However, we should say that there's a way to express those particulars in an interoperable way -- use this technology to do that. And then maybe a note on some examples or something -- or just include examples in an extensibility spec that uses that technology.

[ianbjacobs]

However, we should say that there's a way to express those particulars in an interoperable way -- use this technology to do that.

If we make a decision not to define any semantics, then I think we don't have to discuss "interoperability through other channels" in the API spec.

Ian

[adrianhopebailie]

I may be misinterpreting the question here but here's my thinking.

• Payment method identifiers are keys
• These keys have a many to one relationship with a payment method
• All of the details about how a payment app processes a payment request and builds a payment response and what a website must do with that response is published in the payment method specification or defined somewhere else that publishers can find it.
• The payment method specification also lists all of the identifiers that are currently tied to the payment method that they describe.
• Additional semantics MAY be implied by which identifiers (from the set defined in the payment method specification) are used.

i.e. Listing any of the payment method identifiers for a payment method as supported implies that the payment method itself is supported (i.e. the website/payment app has seen the payment method specification and can process requests and responses formatted according to that spec) but which identifiers are listed indicates to the other party some additional information that is payment method specific.

Examples

Payment Method: Basic Card Payment
Payment Method Identifiers:

• http://w3.org/payments/PMI/card/visa
• http://w3.org/payments/PMI/card/mastercard
• http://w3.org/payments/PMI/card/amex
• http://w3.org/payments/PMI/card/diners
• http://w3.org/payments/PMI/card/cup

Details:
If a website claims support for basic card payments they will use one or more of these identifiers. The specifics of which identifiers are used indicates which card brands they accept.

No special processing is defined for the payment app, it simply returns a response populated with the relevant data.

It is assumed that the website will use the data in the response to initiate a card payment via their normal acquiring channels.

Payment Method: Example Payments
Payment Method Identifiers:

• http://example.com/USD
• http://example.com/EUR
• http://example.com/ZAR

Details:
If a website claims support for example payments they will use one or more of these identifiers. The specifics of which identifiers are used indicates which currencies they accept.

Example Payments may define special processing that a payment app must perform when it gets a request such as a call to a tokenisation web service, downloading of a public key and encryption of the data, or even processing of the payment itself (if this is a credit push payment method).

The processing required of the website when it gets the response will also be defined by the specification and may be very specific (if Example Payments is a proprietary system that has complete control over the payments process) or just general guidance (if Example Payments is a more open system and the processing instructions are more generic like "submit the XYZ data to your local Example Payments gateway".

The data that is in the payment method specific parts of a payment request message will be formatted according to rules in the payment method specification. For payment apps to be inter-operable they need to follow the rules defined in the payment method specification.

Interoperablity is left to the payment method designer to deal with. For example it's quite possible that there will be closed schemes that will write a payment method specification for their scheme but to support the scheme will require that a payment app go through some registration process.

If the payment method has special business processing that payment apps must do then they will likely define that in the payment method specification to.

[ianbjacobs]

Hi @adrianhopebailie,

Thank you for the write-up. Here are some comments on your good list.

Payment method identifiers are keys

That's fine with me, but we need to make a normative statement to that effect.

These keys have a many to one relationship with a payment method

Yes.

All of the details about how a payment app processes a payment request and builds a payment response and what a website must do with that response is published in the payment method specification or defined somewhere else that publishers can find it.

Yes. (I was making the case that they way you find it is to follow the payment-method-identifier-as-URL. But I'm not convincing anyone yet to pursue that.)

The payment method specification also lists all of the identifiers that are currently tied to the payment method that they describe.

I would change "all" to "some". I think that people can independently mint payment method identifiers that make use of an existing payment method spec.

Additional semantics MAY be implied by which identifiers (from the set defined in the payment method specification) are used.

Please say more about what you mean. I very much don't want to put more semantics in the
identifiers themselves; see my early design notes:
https://github.com/w3c/webpayments/wiki/PMI_Notes

Ian

[adrianhopebailie]

Please say more about what you mean.

I think my examples above illustrate the point. To restate one of them, the choice of card related PMIs indicates not only support for basic card payments but ALSO which card brands are supported.

[mattsaxon]

Can I confirm this issue pertains specifically to the “object data” parameter of Payment MethodData

I’m in favour of Ian’s option 2

Here would be an example structure for this to represent the example I was giving for specification of required fields (as per PR #114, which I have closed pending this debate)

  “VISA”: {
    requiredFields: [“cardSecurityCode”, “billingAddress”]
}

“Mastercard”: {
    requiredFields: [“cardSecurityCode”, “billingAddress”]
}

Now, since VISA and Mastercard are very similar (sharing a common field structure as defined in the Basic Card Payment Spec) , it seem to be that it should be possible to form some sort of standardisation here, either by putting the required fields at the top level;

requiredFields: [“cardSecurityCode”, “billingAddress”]

This is not idea as it would apply to other, non-card methods and lead to unexpected behaviour, so this is really a suggestion that we might need some sort of grouping analogous to BasicCardResponse

“BasicCardRequest”: {
    requiredFields: [“cardSecurityCode”, “billingAddress”]
}

We may however find that some fields do indeed apply in a wider scope, e.g. email address, name etc., so here might be an example;

requiredFields: [“emailAddress”, “payeeName”],

“BasicCardRequest”: {
    requiredFields: [“cardSecurityCode”, “billingAddress”]
}

In terms of schemas/WebIDL, we might define the fields at the route to be a base schema with extensions for the embedded object. So BasicCardRequest in this example might inherit from the definition of BaseRequest such that the definition of requiredFields and other items might be reused.

This relates to issue #146

[ianbjacobs]

@mattsaxon,

Can I confirm this issue pertains specifically to the “object data” parameter of Payment MethodData

Yes, the fourth parameter is what I had in mind.

[ianbjacobs]

I believe this issue can be closed because the spec combined parameters 1 and 4 such that:

1. PMIs are used as keys for payment method specific data, and
2. Some grouping is possible (that is: you can say that some data applies to multiple payment methods):

{
supportedMethods: ["bobpay.com"],
data: {
merchantIdentifier: "XXXX",
bobPaySpecificField: true
}

Ian