Extensibility_Notes

Status: This page has no Web Payments Working Group consensus. Ian Jacobs has started this page to gather notes on the topic of extensibility of the components in the Payments Request API set of specifications

See also:

• Spec Notes
• Payment App Notes
• Payment Method Identifier Notes

Payment Message Extensibility [added by Manu]

• a payment message (object), and the sub-objects in a payment message, should be able to be universally identified (via a UUID, URL, or other URI-based mechanism). For example, being able to uniquely identify a payment app, payment instrument, payment response, etc.
• attributes/keys in a payment message (such as "description", "amount", "token", or other data) should be able to be disambiguated in a universal way. Another way to state this is that we should be able to prevent conflicts between two payment apps using a term like "appToken" in a payment response but meaning different things.
• a payment message should be able to include relationships in the message where the relationship refers to an object on a different domain. For example, a payment response referring to an acknowledgement code using a URL or a payment request including a machine-readable terms of service URL for a purchased item. [IJ: this does not seem to be an extensibility requirement]
• a payment message should be able to provide a description in multiple languages where the displayed language is unknown. For example, an English website providing a description for a product in a payment request in English and Spanish.
• a way to associate datatypes with payment message values such as dates and times so that the format for the data is clearly declared [IJ: this does not seem to be an extensibility requirement]
• a way to express the relationships between organizations, products, and payment messages in a single document. [IJ: This is not an extensibility requirement, it is a document organization request.]

Payment App Extensibility

• The API must support registration of and communication with third party payment applications. (This is especially important if third-party mediators are uncommon).
• Any mediator that knows about a registered payment app must have access to update information when that payment app is updated. [Manu: that sounds like a spec in itself]
• It is not a requirement that mediators expose (or share) registration information with other mediators. Although centralizing registration via a third party app could offer convenience for the user by reducing the need for multiple registrations, it is not critical path and therefore should not be part of V1 of the API. issue 38. [Manu] While it's true that sharing of registration information is not required with other mediators, that said, centralizing the information isn't the only way to solve the problem. Not saying we can do this for v1, but I think we should be strongly opposed to centralized solutions unless there is no other viable alternative.
• [MattS] Payment apps must be extensible for both input and output data.

Payment Method Extensibility

Requirements

• The Payment Request API must support diverse payment methods. Payment method inputs and outputs will vary. (We expect payment method specifications to define expected inputs and outputs.)
• The Payment Request API must enable the payer to supply custom data in addition to the data required by the payment method (for input or output).
• [MattS] The merchant and payer should both be able to supply custom data.

Notes

• [Manu] Many of the Payment Message Extensibility section applies to this section as well. The inputs and outputs are just more specific types of payment messages (payment request and payment response).
• The group anticipates publishing a specification that describes how to use JSON-LD with the Payment Request API. issue 45
• [Manu] A better, more generalized approach has been suggested here: http://manu.sporny.org/tmp/wpwg/webpayments/proposals/core-messages/

Payment Mediator Extensibility

• It may be useful (for design purposes) to distinguish the mediator role from the browser role (where the Web application runs).
• It is not a requirement that a browser support third party mediator functionality (because payment applications can fulfill this role). [MattS] I don't believe the Payment App can do all roles, the mediator has a view of all the apps registered and plays a critical role in helping the user choose between apps and instruments issue 103]. [MattS, with agreement from Manu] Whilst I'm happy for this for V1, I would like to see a User-Agent to Mediator interface defined and art of conformance such that the choice of user-agent(browser) does not imply a choice of mediator. This opens the eco-system to allow a payee to choose a single mediator cross-platform which will significantly ease their experience, even on a single system, there may be multiple user-agents and not all of them might be a traditional browser, e.g. embedded WebKit browser in a native app]

Payment Method Identifier Extensibility

Requirements

• It must be possible for the Working Group to mint a payment method identifier for any payment method.
• It must be possible for the anyone to mint a payment method identifier for a payment method under their control.
• It should be possible to use a standard short string to identify common payment methods.
• It must be possible for someone minting a non-standard identifier to make it globally unique in a cost-effective manner.

Notes

• [MattS: It should be possible for someone minting a non-standard identifier to be able to lookup similar methods, or check that their requirement is not met using an exisitng PMI]. [Ian] I don't think this is an extensibility requirement. This is an operations optimization. [Manu] I think I'm a -1 to that MattS, primarily because "similar method" and "requirement is not met" require some way of programmatically doing that comparison.
• In practice, people may use payment method identifiers to group closely related payment methods. The API does not need to know that people are using the APIs in this way.
  • QUESTION: Should we define "not supported" semantics for payment method identifiers for cases where people are using these "broadly applicable" PMIs but want to explicitly exclude more specific ones?
  • [Manu] Seems like if we're going to enable "grouped payment methods" that either you support all of them or not. Providing nuance adds complexity to the implementations and we shouldn't do that unless there are very strong reasons to do so.

Payment Request API Extensibility

Requirements

• The Web Payments Working Group anticipates adding features to a future version of the API. Therefore, implementers must be able to do feature detection. We want to be careful so that we do not hinder our ability to add features. issue 33
• [Manu] If we do feature detection, we should ensure that new features are polyfillable as helper libraries

Notes

• Should the list of transaction types be extensible (see issue 19)? also issue 122. [Manu] Yes, they should. We may have SubscriptionRequest, PreapprovalRequest, and other items. We may find that in 5+ years time that this API turns into more of a "Funds Request" API rather than just a Payment Request API.