Payments Drafts Review

[torgo]

As requested by Ian Jacobs at the AC meeting 22 March 2016.

[sideshowbarker]

I’d like to further suggest that the TAG:

• add the Web Payments WG drafts as an agenda item for the 29-31 March f2f in London
• consider inviting @zkoch and/or @adrianba to call into the portion of the TAG f2f where this will be discussed, to give an overview of the architecture and for a Q&A

(If you do have an agenda item for this, I’d like to call in as well, and maybe @ianbjacobs would as well.)

[torgo]

@sideshowbarker can you post the specific drafts you would like the TAG to review? We are open to putting this on our agenda for this week still. We could discuss on Wednesday afternoon UK time or Thursday afternoon UK time. Would those times suit the tz needs of yourself, @ianbjacobs and/or @zkoch, @adrianba ?

[torgo]

https://w3c.github.io/browser-payment-api/specs/paymentrequest.html ?

[sideshowbarker]

https://w3c.github.io/browser-payment-api/specs/paymentrequest.html ?

Yes.

@sideshowbarker can you post the specific drafts you would like the TAG to review?

The complete list of the current drafts is:

• Payment Request API Architecture
  https://w3c.github.io/browser-payment-api/specs/architecture.html
• Payment Request API
  https://w3c.github.io/browser-payment-api/specs/paymentrequest.html
• Payment Method Identifiers
  https://w3c.github.io/browser-payment-api/specs/method-identifiers.html
• Basic Card Payment
  https://w3c.github.io/browser-payment-api/specs/basic-card-payment.html

Among those I’d think the TAG would probably want to start by looking at the Architecture doc, before looking at the Payment Request API spec, which defines the core (browser/JavaScript) API.

We could discuss on Wednesday afternoon UK time or Thursday afternoon UK time.

Both of those would work fine for me, but I think it’s most important to have either @zkoch or @adrianba on—or both (I think they’re both US/West).

[sideshowbarker]

oops in my previous comment I put the (not-yet-existing) TR URL for the architecture doc. Please instead use https://w3c.github.io/browser-payment-api/specs/architecture.html (and edited my other comment to correct the URL there too)

[ianbjacobs]

Hi TAG!

Thank you for taking this early opportunity to review the Web Payment WG specs. I suggest focusing on the Payment Request API and the Payment Method Identifiers specs. There are some good TAG questions in their like "what identifiers should we use for payment methods?"

The architecture document has multiple parts, some of which are simply informative (such as explaining how we organized the documents in this set). The more architectural bit involves a description of "how all of this is expected to work from the user perspective."

The Basic Card Payment spec is an example of the sort of spec we anticipate for each new payment method that people wish to use via the API. It describes (in this case) the required inputs and outputs for handling card payments. Anyone will be able to publish this sort of spec to tell the world how to support different payment methods interoperably through this API. (I do not yet know how many such payment method specs the WG itself will publish.)

We will also want to engage the TAG around "payment app registration" but we do not yet have a spec for it.

Thanks again,

Ian

[triblondon]

@sideshowbarker @ianbjacobs if we schedule this for 5pm London time (UTC+1) tomorrow, can you join a Google Hangout and organise to bring in others as you feel appropriate?

[sideshowbarker]

@sideshowbarker @ianbjacobs if we schedule this for 5pm London time (UTC+1) tomorrow, can you join a Google Hangout and organise to bring in others as you feel appropriate?

Works for me but I defer to @ianbjacobs and of course to @zkoch and @adrianba as far as their availability

[zkoch]

UTC+1 tomorrow would work for me.

[triblondon]

OK, folks, could you add me (triblondon) on Skype? I'll call you at 5pm UK time today (30 March). We haven't heard from @adrianba so can we go ahead or should we reschedule to allow Adrian time to opt in?

[sideshowbarker]

We haven't heard from @adrianba so can we go ahead or should we reschedule to allow Adrian time to opt in?

Let’s go ahead as scheduled at 5pm UK time today. I still hope Ade will be able to join also, but if needed Zach on his own can handle doing the overview and Q&A from the editors’ perspective.

[torgo]

@triblondon agreed at our London f2f to take this for the technical review.

[triblondon]

Travis, Mark and I are doing reviews.

[triblondon]

OK, this is my first attempt at a TAG spec review, so please tell me how I'm cocking it up so I can do it better.

Overview

My understanding is that this API enables a native browser UI to sit between a 'pay' button on a website and the resulting submission of payment credentials to the merchant.

In the simplest case, this is not much more than what we have seen before with requestAutocomplete - the new API essentially just turns a web based credit card form into a native one. The merchant receives raw credit card data, and then processes it in whatever way they want (which would include hundreds of possible processing service providers).

However, the majority of the architectural complexity of this draft is in anticipation of token based payment systems, where the user would hit Pay, choose to use a token generating payment app, and that would invoke a request directly to the payment app provider. The payment app provider, having authenticated the user and confirmed their consent, would generate a single-use token binding the merchant, the amount and the date and sent that back through the browser to be handed back to the merchant web page. The merchant would then submit that to their server and use it in an exchange between the merchant's servers and those of the payment app, to settle the transaction. Being largely unopinionated enables this API to be compatible with a variety of payment settlement workflows, so it would also work with bitcoin, for example.

High level questions

1. The payment app UI anticipated by the spec - would that be web UI? How would it be displayed to the user - in a new modal browsing context? And will the spec define separately how payment apps are to interact with a PaymentRequest, or are they expected to do so using the same methods as the merchant?
2. If the most likely early payment apps will simply return raw credit card credentials back to the merchant, is there an anticipated roadmap for how those apps would evolve? For example, would a next stage be a token generating payment app backed by a credit card? I guess I'm saying what is the likely progression and does the spec make any conscious design decisions based on the likely phases of adoption/support from banks or the payments industry?
3. There seems to be little specific support for recurring payments. I expected to see a lot more of that, and would be concerned if this API didn't support use cases such as:

• Pay $20 to Conde Nast for a subscription to Vogue, allow CN to charge the same amount on a monthly basis until the authority is cancelled by the user
• Set up a payment authority to Amazon to charge for AWS usage, which is billed on the same day of each month but for a different amount

Spec specifics

One principle of the Payment Request system is that when a merchant web site declares that it accepts a given payment method then it must know how to process the resulting response

This implies that a payment method identifier is strongly coupled to the response format for that method. If the response format changed, you would need a new method identifier. Is that an issue?

three key parties in every transaction

These are cited as being the user, the merchant, and the payment method. However, a payment method is an instrument, not a party, surely? Wouldn't the party be the payment app provider? And is it necessary to acknowledge that in some cases the payment app provider may not be the same as the party with whom the merchant finalises the transaction, especially in the case of a basic card payment?

Issue 15 discusses the format of arguments to the paymentrequest constructor. I'm strongly in favour of these being merged into a single object, which provides greater extensibility, and is more in line with the direction of travel of JavaScript now that destructuring makes dealing with large object structures easy.

paymentRequest.complete feels slightly weird, and I'm wondering why the merchant page does not instead receive an unresolved promise that it can resolve or reject. That would seem more aligned with the use of promises elsewhere.

Issue 40 describes non payment method specific data - would that be data specific to a payment app then? AFAICT, the merchant doesn't know about payment apps, only payment methods, so it's hard to see how custom data not tied to a payment method could be useful. The issue is a bit unclear on what the core problem is here.

Issue 16 discusses the method of instantiation of the PR object. I prefer a constructor. I'd definitely say no to a singleton unless it was a solid certainty that we'll never want a UA to be processing multiple payments at a time, since the instance provides a means of storing state which seems like it would become more useful as the API is extended in future.

I'm wondering if show() is poorly named, since in some cases a payment app may be able to fully automate its response without user interaction, in which case nothing would actually be shown. is that ever a possibility?

Issue 23 and issue 4 discuss the ability for merchants to express a payment method preference and to charge differently for different payment methods. Merchant preference seems basically meaningless unless there is a charge element - the user has no reason to choose a particular payment method simply because the merchant wants them to, but they would certainly be swayed if using one method added a surcharge. Perhaps the simplest way to model that would be to have the merchant pre-calculate a supplement charge to attach to the payment method at the PaymentRequest level, rather than polluting the PaymentDetails items dictionary with multiple additional charges per item (this is suggested in w3c/payment-request#4 (comment), which I agree with). I'm concerned that any potential desire to add granularity to the cost of an individual item will get multi-dimensional very quickly - eg supporting different charges based on payment method, and also expressing pricing in different currencies, you would need a value for each intersection of that possibility space.

Issue 2 discussed whether iframes should be able to request payment. It seems like a severe limitation to me to prohibit that mode of use.

Issue 18 discusses the format of the PaymentDetails dictionary and the special case treatment of the final 'sum' item. I'm very strongly in favour of breaking this out into a separate element. To me it has no business being in that sequence. In fact I'm dubious of the need for an explicit total at all.

If the sequence is empty, then this indicates that the merchant cannot ship to the current shippingAddress.

shippingOptions appears not to support the idea of a transaction that does not require shipping (eg a digital service). This is covered off by the PaymentOptions interface but it would be worth clarifying that shippingOptions is only expected to be supplied by the merchant when they are also requesting shipping address in PaymentOptions

Should the merchant be able to request your email and recipient phone number

Issue 1. Yes. Otherwise you will end up with a paymentrequest flow leading into a conventional webform to collect all the data the PR API is failing to deliver. Email and phone number are really obvious and will be needed by lots of merchants.

Should the web page be able to provide status information before calling complete()

Issue 5. Yes. Unless the API can set out guarantees or limits on the duration of the merchant's payment processing, it must support feedback. It's also out of the scope of this API to understand whether a payment method contains distinct phases to its settlement process, and if it does, but those cannot be surfaced, PR may be an inferior user experience to the current methods available to merchants.

[sideshowbarker]

Thanks @triblondon—I’ve raised w3c/payment-request#118 for tracking the action on responding to your review from the Web Payments WG side.

[sideshowbarker]

from @triblondon:

Issue 15 discusses the format of arguments to the paymentrequest constructor. I'm strongly in favour of these being merged into a single object, which provides greater extensibility, and is more in line with the direction of travel of JavaScript now that destructuring makes dealing with large object structures easy.

Thanks @triblondon. This seems like an important issue, so I would like to hear from more of the TAG (e.g., @mnot, @travisleithead) about whether this is how the TAG recommends that groups design JavaScript APIs. Do either https://www.w3.org/TR/api-design/ or https://w3ctag.github.io/design-principles/ provide some relevant guidance on this?

[msporny]

@triblondon wrote:

Issue 16 discusses the method of instantiation of the PR object. I prefer a constructor. I'd definitely say no to a singleton unless it was a solid certainty that we'll never want a UA to be processing multiple payments at a time, since the instance provides a means of storing state which seems like it would become more useful as the API is extended in future.

To clarify, the singleton would instantiate a Promise and return it. You'd be able to run multiple payment requests in a page. I'm not strongly arguing for/against - just clarifying.

[msporny]

I'm wondering if show() is poorly named, since in some cases a payment app may be able to fully automate its response without user interaction, in which case nothing would actually be shown. is that ever a possibility?

The Web Payments Community Group Browser API specification proposed .start():

http://wicg.github.io/web-payments-browser-api/checkout-api.html#simple-checkout-example

[adrianhopebailie]

@triblondon

Thanks for this feedback.

It may help to have a look at the original architecture that was put in the wiki prior to the specs being drafted: https://github.com/w3c/webpayments/wiki/A-Payments-Initiation-Architecture-for-the-Web

Some of this is now reflected in the architecture document but some still needs to be pulled through in documents about payment apps and registration and non-browser payments:

Some proposals exist for these:

• http://w3c.github.io/webpayments/proposals/web-payments-http-api/index.html
• https://w3c.github.io/webpayments/proposals/paymentapps/payment-apps.html

To answer some of your questions:

The payment app UI anticipated by the spec - would that be web UI? How would it be displayed to the user - in a new modal browsing context? And will the spec define separately how payment apps are to interact with a PaymentRequest, or are they expected to do so using the same methods as the merchant?

We have intentionally not prescribed this as we hope that payment apps will take a variety of forms depending on the deployment scenario. My position (chair hat on) is that we should prescribe a minimum web-based interface between the browser and a web-based payment app where the paymentRequest is serialized as JSON and sent via a POST to the endpoint URL of the payment app which responds with HTML that is rendered as the app UI.

My expectation is that the paymentRequest will be presented to the payment app purely as JSON serialized data (also see w3c/payment-request#45 and w3c/payment-request#47) so I don't presume we'll prescribe how the app will interact with the paymentRequest however there may be pending proposals that suggest otherwise.

If the most likely early payment apps will simply return raw credit card credentials back to the merchant, is there an anticipated roadmap for how those apps would evolve? For example, would a next stage be a token generating payment app backed by a credit card? I guess I'm saying what is the likely progression and does the spec make any conscious design decisions based on the likely phases of adoption/support from banks or the payments industry?

The architecture intentionally tries to make the API very agnostic to payment methods and puts all of the method specific logic into stand-alone payment method specifications. The Basic Card Payment spec is one of these but the group recently resolved to produce a number of them based on the various payment flows that have been investigated. This will be entirely dependent on WG input to produce these. The flows TF has been primarily responsible for this work to date under the guidance of @mattsaxon. See more flows related stuff here: https://github.com/w3c/webpayments-flows

There seems to be little specific support for recurring payments.

This is an issue that the group is actively discussing. There is one PR proposing a mechanism to deal with this use case (w3c/payment-request#111) and two related issues (w3c/payment-request#19 and w3c/payment-request#113). Your input on those threads would be greatly appreciated.

One principle of the Payment Request system is that when a merchant web site declares that it accepts a given payment method then it must know how to process the resulting response

This implies that a payment method identifier is strongly coupled to the response format for that method. If the response format changed, you would need a new method identifier. Is that an issue?

Correct. Our expectation is that these formats will not change often. There is very little required to mint new identifiers so we expect that when payment apps and processors introduce changes to a payment method they will be non-breaking or introduces as new, versioned, payment methods. Example: http://w3.org/payments/basic-card could become http://w3.org/payments/basic-card/v2

three key parties in every transaction

These are cited as being the user, the merchant, and the payment method. However, a payment method is an instrument, not a party, surely? Wouldn't the party be the payment app provider? And is it necessary to acknowledge that in some cases the payment app provider may not be the same as the party with whom the merchant finalizes the transaction, especially in the case of a basic card payment?

I agree that this needs revising. The traditional model for payments is the "4-party" model and I think we'd do well to describe the architecture in this context. The architecture puts the user agent in the role of mediator between the payer (and their PSP - likely the payment app issuer) and the merchant (and possibly their PSP too).

To address some of your other comments I have either added them to the relevant issue:

• Should the merchant be able to request your email and recipient phone number w3c/payment-request#1
• Should the Payment Request API only be available in a top-level browsing context? w3c/payment-request#2
• Should it be possible to vary amounts depending on payment method w3c/payment-request#4
• Should the web page be able to provide status information before calling complete() w3c/payment-request#5
• Combine API parameters into a single request object + options w3c/payment-request#15
• Use navigator.payments singleton, factory method, or PaymentRequest constructor w3c/payment-request#16
• Constructor should not include "total" in list of items w3c/payment-request#18
• Can the merchant influence order of presentation of payment apps to the user w3c/payment-request#23

Or created a new issue:

• Update Introduction to describe actors better w3c/payment-request#121
• Consider revising the design of complete() w3c/payment-request#122
• Should show() be renamed? w3c/payment-request#127
• Add explicit note that shippingOptions is only required if requesting shipping w3c/payment-request#128

[triblondon]

Thanks @adrianhopebailie. Glad it was useful, and I'll follow up with a few comments in your repos.

[triblondon]

I think we're done here.