path: root/chromium/components/payments/mojom/payment_request.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.

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

// The shipping address that the browser process provides to the renderer
// process. Built either by the browser or a payment app.
struct PaymentAddress {
  // ISO 3166 country code. Two upper case ASCII letters.
  string country;

  array<string> address_line;
  string region;
  string city;
  string dependent_locality;
  string postal_code;
  string sorting_code;

  // Optional shortest ISO 639 language code. Two or three lower case ASCII
  // letters.
  string language_code;

  // Optional ISO 15924 script code. Four ASCII letters. The first letter is
  // upper case; the rest are lower case.
  string script_code;

  string organization;
  string recipient;
  string phone;
};

// The currency amount that the renderer provides to the browser process. The
// browser shows the amount in UI and forwards it on to the payment app, if it
// requires the amount.
struct PaymentCurrencyAmount {
  // The most common identifiers are three-letter alphabetic codes as defined
  // by [ISO4217] (for example, "USD" for US Dollars), however any string of at
  // most 2048 characters is considered valid.
  string currency;

  // ISO 20022 CurrencyAnd30Amount. Up to 30 total digits. Up to 10 fraction
  // digits. Separated by a dot.
  string value;

  // currency_system is a URL that indicates the currency system that the
  // currency identifier belongs to. By default, the value is
  // urn:iso:std:iso:4217 indicating that currency is defined by [ISO4217]
  // (for example, USD for US Dollars).
  string currency_system = "urn:iso:std:iso:4217";
};

struct PaymentResponse {
  string method_name;

  // Payment method specific JSON string that is built either by the browser or
  // a payment app, for example Android Pay. Browser ensures that the string can
  // be successfully parsed into base::JSONParser. Renderer parses this string
  // via v8::JSON::Parse() and hands off the result to the merchant website.
  // There's no one format for this object, so more specific types cannot be
  // used. A simple example:
  //
  // {"nameOnCard": "Jon Doe", "pan": "4111 1111 1111 1111"}
  string stringified_details;

  PaymentAddress? shipping_address;
  string? shipping_option;
  string? payer_name;
  string? payer_email;
  string? payer_phone;
};

enum PaymentErrorReason {
  UNKNOWN,
  USER_CANCEL,
  NOT_SUPPORTED
};

enum CanMakePaymentQueryResult {
  CAN_MAKE_PAYMENT,
  CANNOT_MAKE_PAYMENT,
  QUERY_QUOTA_EXCEEDED,

  // Used only on localhost and file:// schemes to warn web developer that the
  // query quota has exceeded, but Chrome is returning an answer anyway.
  WARNING_CAN_MAKE_PAYMENT,
  WARNING_CANNOT_MAKE_PAYMENT,
};

interface PaymentRequestClient {
  OnShippingAddressChange(PaymentAddress address);
  OnShippingOptionChange(string shipping_option_id);
  OnPaymentResponse(PaymentResponse response);
  OnError(PaymentErrorReason error);
  OnComplete();
  OnAbort(bool aborted_successfully);
  OnCanMakePayment(CanMakePaymentQueryResult result);
  WarnNoFavicon();
};

struct PaymentItem {
  string label;
  PaymentCurrencyAmount amount;
  bool pending;
};

struct PaymentShippingOption {
  string id;
  string label;
  PaymentCurrencyAmount amount;
  bool selected;
};

enum AndroidPayEnvironment {
  PRODUCTION,
  TEST
};

enum AndroidPayCardNetwork {
  AMEX,
  DISCOVER,
  MASTERCARD,
  VISA
};

enum AndroidPayTokenization {
  UNSPECIFIED,
  GATEWAY_TOKEN,
  NETWORK_TOKEN
};

struct AndroidPayTokenizationParameter {
  string? key;
  string? value;
};

enum BasicCardNetwork {
  AMEX,
  DINERS,
  DISCOVER,
  JCB,
  MASTERCARD,
  MIR,
  UNIONPAY,
  VISA
};

enum BasicCardType {
  CREDIT,
  DEBIT,
  PREPAID
};

struct PaymentMethodData {
  array<string> supported_methods;

  // A JSON string built by the renderer from a JavaScript object that the
  // merchant 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 payment apps. There's
  // no one format for this object, so more specific types cannot be used. A
  // simple example:
  //
  // {"gateway": "stripe"}
  string stringified_data;

  // Android Pay specific method data is parsed in the renderer.
  // https://developers.google.com/web/fundamentals/getting-started/primers/payment-request/android-pay
  // TODO(rouslan): Stop parsing Android Pay data. http://crbug.com/620173
  AndroidPayEnvironment environment;
  string? merchant_name;
  string? merchant_id;
  array<AndroidPayCardNetwork> allowed_card_networks;
  AndroidPayTokenization tokenization_type;
  array<AndroidPayTokenizationParameter> parameters;
  // Value of 0 means the merchant did not specify or it was an invalid value.
  int32 min_google_play_services_version;

  // Basic card specific method data is parsed in the renderer.
  array<BasicCardNetwork> supported_networks;
  array<BasicCardType> supported_types;
};

struct PaymentDetailsModifier {
  PaymentItem? total;
  array<PaymentItem> additional_display_items;
  PaymentMethodData method_data;
};

struct PaymentDetails {
  PaymentItem? total;
  array<PaymentItem> display_items;
  array<PaymentShippingOption> shipping_options;
  array<PaymentDetailsModifier> modifiers;
  string error = "";
  // Identifier identifying the payment request, to be exposed
  // to payment apps. It is optional since this structure is used
  // by PaymentDetailsUpdate (next to PaymentDetailsInit) but
  // PaymentDetailsUpdate has no id.
  string? id;
};

enum PaymentShippingType {
  SHIPPING,
  DELIVERY,
  PICKUP
};

struct PaymentOptions {
  bool request_payer_name;
  bool request_payer_email;
  bool request_payer_phone;
  bool request_shipping;
  PaymentShippingType shipping_type;
};

enum PaymentComplete {
  SUCCESS,
  FAIL,
  UNKNOWN
};

interface PaymentRequest {
  Init(PaymentRequestClient client,
       array<PaymentMethodData> method_data,
       PaymentDetails details,
       PaymentOptions options);
  Show();
  UpdateWith(PaymentDetails details);
  Abort();
  Complete(PaymentComplete result);
  CanMakePayment();
};