chromium/third_party/blink/public/mojom/payments/payment_handler_host.mojom

// Copyright 2019 The Chromium Authors
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.

[JavaPackage="org.chromium.payments.mojom"]
module payments.mojom;

import "components/payments/mojom/payment_request_data.mojom";
import "third_party/blink/public/mojom/payments/payment_request.mojom";

struct PaymentHandlerMethodData {
  // Either a short string (e.g., "basic-string") or URL (e.g.,
  // "https://google.com/pay") payment method name.
  string method_name;

  // A JSON string built by the renderer from a JavaScript object that the
  // website provides. The renderer uses blink::JSONObject::toJSONString() to
  // generate this string. The browser does not parse the string and passes it
  // as-is directly to the payment handler. There's no one format for this
  // object, so more specific types cannot be used. A simple example:
  //
  // {"supportedNetworks": ["visa"]}
  string? stringified_data;
};

struct PaymentHandlerModifier {
  PaymentCurrencyAmount? total;
  PaymentHandlerMethodData method_data;
};

// Constructed by the browser based on PaymentDetails from the Merchant
// renderer. The browser sends this to the Payment Handler renderer.
struct PaymentRequestDetailsUpdate {
  PaymentCurrencyAmount? total;
  array<PaymentShippingOption>? shipping_options;
  array<PaymentHandlerModifier>? modifiers;
  string error = "";
  string? stringified_payment_method_errors;
  AddressErrors? shipping_address_errors;
};

// The interface for a PaymentRequest object in the browser, so a PaymentHandler
// renderer can talk to it.
//
// Implemented in the browser process. Not sandboxed.
// Desktop (Windows, ChromeOS, Linux, MacOS) implementation:
//   components/payments/content/payment_request.h
interface PaymentHandlerHost {
  // Called by the Payment Handler renderer to let the browser know that the
  // user has selected a different payment instrument or shipping option, or
  // when the user has changed the shipping address.
  //
  // The browser validates the |method_data|, |shipping address|, or
  // |shipping option_id| and passes it on to the Merchant renderer via one of
  // the following methods which are all defined in
  // third_party/blink/public/mojom/payments/payment_request.mojom:
  // PaymentRequestClient.OnPaymentMethodChange(method_name,stringified_data),
  // PaymentRequestClient.OnShippingAddressChange(PaymentAddress address),
  // PaymentRequestClient.OnShippingOptionChange(string shipping_option_id).
  //
  // The Merchant renderer then responds to the browser via
  // PaymentRequest.UpdateWith(details) to update the total or other details of
  // the payment request based on the selected instrument/shipping address/
  // shipping option or PaymentRequest.OnPaymentDetailsNotUpdated() if the
  // total and other details are unchanged. The total can change, for example,
  // based on the billing address of the selected instrument or the selected
  // shipping address/option. The list of available shipping options can change
  // based on the selected shipping address.
  //
  // The browser validates the |details| from the Merchant renderer and sends
  // their subset to the Payment Handler renderer as
  // |PaymentRequestDetailsUpdate|, so it can show the updated details.
  ChangePaymentMethod(PaymentHandlerMethodData method_data) =>
      (PaymentRequestDetailsUpdate response_data);
  ChangeShippingOption(string shipping_option_id) =>
      (PaymentRequestDetailsUpdate response_data);
  ChangeShippingAddress(PaymentAddress shipping_address) =>
      (PaymentRequestDetailsUpdate response_data);
};