Re: [w3ctag/spec-reviews] Payments Drafts Review (#109)

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 https://github.com/w3c/browser-payment-api/issues/4#issuecomment-200560457, 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.

---
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3ctag/spec-reviews/issues/109#issuecomment-204992438