[Payments] Implement payment instrument icons

components/payments/mojom/payment_app.mojom

 // Copyright 2016 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 module payments.mojom;
 
 import "components/payments/mojom/payment_request.mojom";
 import "mojo/common/time.mojom";
 import "url/mojo/url.mojom";
 
 enum PaymentHandlerStatus {
   SUCCESS,
   NOT_IMPLEMENTED,
   NOT_FOUND,
   NO_ACTIVE_WORKER,
   STORAGE_OPERATION_FAILED,
+  FETCH_INSTRUMENT_ICON_FAILED,
 };
 
+// This struct is provided to hold an image object from render side (ImageObject.idl). 

[dcheng, 2017/06/13 09:02:55]

Nit: 80 chars

[gogerald1, 2017/06/13 15:37:19]

Done.

+struct ImageObject {
+  url.mojom.Url src;
+};
+
+// This struct is provided to hold a payment instrument from render side (PaymentInstrument.idl).

[dcheng, 2017/06/13 09:02:55]

To elaborate: my questions are more of "what is a payment instrument? What does
it represent? What are the methods and capabilities that are the fields"?

As someone who's not familiar with the payments spec, these fields are pretty
mysterious.

[gogerald1, 2017/06/13 15:37:19]

These structures and interfaces are almost exactly match the structures and
interfaces in the spec, so I think the best place to understand them is the
spec. We already put the links in the corresponding *.idl, like here
https://cs.chromium.org/chromium/src/third_party/WebKit/Source/modules/paymen...
Someone who want read or change these codes have to know the spec first. 
Make sense?

[dcheng, 2017/06/13 17:33:15]

- Web specs are not the easiest thing to understand
- It's not helpful to jump between pages (that might disappear) when trying to
understand code
- Seems contrary to the guidelines to have more comments for non-obvious things
(https://chromium.googlesource.com/chromium/src/+/master/styleguide/c++/blink-...)

But we can address this in a followup.

[zino, 2017/06/13 18:02:43]

There are two specs PaymentRequest API and PaymentHandler API.

Term:
UA (You already know well :-) )
Merchant (e.g. Amazon)
Third-party Payment App Provider (e.g. PayPal)

The PaymentRequest API is a mediator role between them.
Traditionally, mechants had to connect to third-party providers for payment
directly.
It made so many each different ways for connection for a long time.

But now, mechants can use PaymentRequest API for payment. The API doesn't
provide any payment methods but can connect to third-party providers indirectly.
Actual payment process will run on server backend in merchant side but this way
has some advances. (e.g. improving UX, reducing integration efforts)

On the other hands, PaymentHandler API provides a way to make third-party
payment apps based on the web-standard way.
This patch is related to the PaymentHandler API and the PaymentInstrument is an
actual payment instrument such as credit card, bit coin, mileage or other
things.
The PaymentInstrument data will be used to display instrument UI[1] on
PaymentSheet UI created by PaymentRequest API.

FYI, PaymentHandler API is implemented by extending service worker like push
API. So, third-party providers can write codes to provider payment app as
follows:

navgiator.serviceWorker.register('payment.js')
    .then(...)
    .then(registration => {
        registration.paymentManager.paymentInstrument.set({
             name: "Test Pay",
             icons: [{
                 ...
             }]
        });
    });

Once above code runs via user interaction(accessing the payment app provider
site? or something?), then the payment instrument data is stored in browser.
and then browser can display the stored payment instruments when some payment
request is initiated from merchant site.

Although it's an old thing, this PPT might help your understanding.
  -
https://docs.google.com/presentation/d/1rQ4SW3huSTKOSHc97ebnhYWa7UfJt4swHeFlS...

[1] The screenshot was provided in this bug tracking:
https://bugs.chromium.org/p/chromium/issues/detail?id=720029

[gogerald1, 2017/06/14 01:28:16]

Acknowledged.

 struct PaymentInstrument {
   string name;
+  array<ImageObject> icons;
   array<string> enabled_methods;
   string stringified_capabilities;
 };
 
+// This interface provides implementation of PaymentInstruments.idl in render side. 
 interface PaymentManager {
   Init(string service_worker_scope);
   DeletePaymentInstrument(string instrument_key)
       => (PaymentHandlerStatus status);
   GetPaymentInstrument(string instrument_key)
       => (PaymentInstrument instrument, PaymentHandlerStatus status);
   KeysOfPaymentInstruments()
       => (array<string> keys, PaymentHandlerStatus status);
   HasPaymentInstrument(string instrument_key)
       => (PaymentHandlerStatus status);
   SetPaymentInstrument(string instrument_key, PaymentInstrument instrument)
       => (PaymentHandlerStatus status);
   ClearPaymentInstruments()
       => (PaymentHandlerStatus status);
 };
 
+// This struct is provided to send payment request data to render side (PaymentRequestEvent.idl).
 struct PaymentRequestEventData {
   url.mojom.Url top_level_origin;

[dcheng, 2017/06/13 09:02:55]

Similarly, what are the two origins here, why do we need both, what are they
used for

[gogerald1, 2017/06/13 15:37:19]

Please refer the spec here
https://w3c.github.io/payment-handler/#the-paymentrequestevent

   url.mojom.Url payment_request_origin;
   string payment_request_id;

[dcheng, 2017/06/13 09:02:55]

Is there any structure to the payment request IDs? What can be in method data
below? What are modifiers? What's the instrument key?

[gogerald1, 2017/06/13 15:37:19]

Please refer the spec here
https://w3c.github.io/payment-handler/#the-paymentrequestevent

   array<PaymentMethodData> method_data;
   PaymentItem total;
   array<PaymentDetailsModifier> modifiers;
   string instrument_key;
 };
 
+// This struct is provided to receive payment app response from render side (PaymentAppResponse.idl).
 struct PaymentAppResponse {
   string method_name;
   string stringified_details;
 };
 
 // This interface is provided to pass a payment app response from payment
 // request event in renderer side to browser side by calling respondWith().
 interface PaymentAppResponseCallback {
   OnPaymentAppResponse(PaymentAppResponse response,
                        mojo.common.mojom.Time dispatch_event_time);
 };