// Copyright 2016 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 "mojo/public/mojom/base/time.mojom";
import "third_party/blink/public/mojom/payments/payment_credential.mojom";
import "url/mojom/origin.mojom";
import "url/mojom/url.mojom";
import "third_party/blink/public/mojom/webauthn/authenticator.mojom";
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;
PayerDetail payer;
// The assertion for secure payment confirmation.
blink.mojom.GetAssertionAuthenticatorResponse? get_assertion_authenticator_response;
};
struct PayerDetail {
string? email;
string? name;
string? phone;
};
enum PaymentErrorReason {
UNKNOWN,
USER_CANCEL,
NOT_SUPPORTED,
NOT_SUPPORTED_FOR_INVALID_ORIGIN_OR_SSL,
ALREADY_SHOWING,
INVALID_DATA_FROM_RENDERER,
NOT_ALLOWED_ERROR,
USER_OPT_OUT,
USER_ACTIVATION_REQUIRED,
};
enum CanMakePaymentQueryResult {
CAN_MAKE_PAYMENT,
CANNOT_MAKE_PAYMENT,
};
enum HasEnrolledInstrumentQueryResult {
HAS_ENROLLED_INSTRUMENT,
HAS_NO_ENROLLED_INSTRUMENT,
QUERY_QUOTA_EXCEEDED,
// Used only on localhost and file:// schemes to warn web developer that the
// query quota has been exceeded, but Chrome is returning an answer anyway.
WARNING_HAS_ENROLLED_INSTRUMENT,
WARNING_HAS_NO_ENROLLED_INSTRUMENT,
};
// Implemented in the renderer process. Sandboxed. Deals with untrusted data.
// Implementation: third_party/blink/renderer/modules/payments/payment_request.h
// Important: these methods are asynchronous. For example, when Blink calls:
// PaymentRequest request = new PaymentRequest();
// request.canMakePayment();
// and when Java's PaymentRequest#init() invokes PaymentRequestClient#onError(),
// the execution sequence would be:
// Blink: PaymentRequest request = new PaymentRequest();
// Blink: request.canMakePayment();
// Java: PaymentRequest#init()
// Java: PaymentRequestClient#onError()
// Java: PaymentRequest#canMakePayment()
// Blink: request.onError()
interface PaymentRequestClient {
OnPaymentMethodChange(string method_name, string stringified_details);
OnShippingAddressChange(PaymentAddress address);
OnShippingOptionChange(string shipping_option_id);
OnPayerDetailChange(PayerDetail detail);
OnPaymentResponse(PaymentResponse response);
OnError(PaymentErrorReason error, string error_message);
OnComplete();
OnAbort(bool aborted_successfully);
OnCanMakePayment(CanMakePaymentQueryResult result);
OnHasEnrolledInstrument(HasEnrolledInstrumentQueryResult result);
WarnNoFavicon();
// Check whether the frame that instantiated this PaymentRequest object has a
// Content Security Policy (CSP) connect-src directive that allows connecting
// to the given URL. Called before the browser process downloads a payment
// manifest or follows its redirect.
AllowConnectToSource(
url.mojom.Url url,
url.mojom.Url url_before_redirects,
bool did_follow_redirect) => (bool allow);
};
struct PaymentItem {
string label;
PaymentCurrencyAmount amount;
bool pending;
};
struct PaymentShippingOption {
string id;
string label;
PaymentCurrencyAmount amount;
bool selected;
};
enum AndroidPayEnvironment {
PRODUCTION,
TEST
};
enum BasicCardNetwork {
AMEX,
DINERS,
DISCOVER,
JCB,
MASTERCARD,
MIR,
UNIONPAY,
VISA
};
// Parameters for the "secure-payment-confirmation" payment method identifier.
// https://w3c.github.io/secure-payment-confirmation
struct SecurePaymentConfirmationRequest {
// A list of WebAuthn credential identifiers. These values will be looked up
// in "secure_payment_confirmation_instrument" table. Upon user gesture, one
// of these credentials will be queried from WebAuthn.
array<array<uint8>> credential_ids;
// An indefinite-length blob passed from the relying party server, to be sent
// to an authenticator for signing.
array<uint8> challenge;
// The name and icon of the payment instrument to display to the user and to
// be sent to the authenticator device for signing.
blink.mojom.PaymentCredentialInstrument instrument;
// Time to wait for an authenticator to complete an operation provided by the
// relying party.
mojo_base.mojom.TimeDelta? timeout;
// The origin of the payee that will be displayed in the payment confirmation
// dialog and will be sent to the authenticator device for signing.
url.mojom.Origin? payee_origin;
// The name of the payee that will be displayed in the payment confirmation
// dialog and will be sent to the authenticator device for signing.
string? payee_name;
// The relying party ID that must match the relying party of a credential.
string rp_id;
// Webauthn extensions to be set on the credential request.
blink.mojom.AuthenticationExtensionsClientInputs? extensions;
// Whether or not to render an 'opt out' experience on the browser-hosted UX,
// which allows the user to indicate to the RP that they wish to remove any
// RP-stored information.
bool show_opt_out;
// Experimental members that allow specifying information about the card
// network and issuer, including icons for both. These are controlled by the
// SecurePaymentConfirmationNetworkAndIssuerIcons Blink runtime feature.
NetworkOrIssuerInformation? network_info;
NetworkOrIssuerInformation? issuer_info;
};
struct NetworkOrIssuerInformation {
string name;
url.mojom.Url icon;
};
struct PaymentMethodData {
string supported_method;
// 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;
// Value of 0 means the merchant did not specify or it was an invalid value.
int32 min_google_play_services_version;
// Value of 0 means the merchant did not specify or it was an invalid value.
int32 api_version;
// Basic card specific method data is parsed in the renderer.
array<BasicCardNetwork> supported_networks;
// Parameters for the "secure-payment-confirmation" payment method identifier.
SecurePaymentConfirmationRequest? secure_payment_confirmation;
};
struct PaymentDetailsModifier {
PaymentItem? total;
array<PaymentItem> additional_display_items;
PaymentMethodData method_data;
};
struct PaymentDetails {
PaymentItem? total;
// If any of these lists is null, then PaymentRequest.UpdateWith() ignores
// them. If any of these lists are empty, then PaymentRequest.UpdateWith()
// clears the corresponding lists in the browser.
array<PaymentItem>? display_items;
array<PaymentShippingOption>? shipping_options;
array<PaymentDetailsModifier>? modifiers;
string error = "";
AddressErrors? shipping_address_errors;
// 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;
string? stringified_payment_method_errors;
};
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 {
FAIL,
SUCCESS,
UNKNOWN
};
// Implemented in the browser process. Not sandboxed. Deals with trusted data.
// Android implementation (Clank, WebLayer):
// components/payments/content/android/java/src/org/chromium/components/payments/MojoPaymentRequestGateKeeper.java
// Desktop (Windows, ChromeOS, Linux, MacOS) implementation:
// components/payments/content/payment_request.h
interface PaymentRequest {
// Instantiates the renderer-browser connection with the information from the
// JavaScript constructor of PaymentRequest.
Init(pending_remote<PaymentRequestClient> client,
array<PaymentMethodData> method_data,
PaymentDetails details,
PaymentOptions options);
// Shows the user interface with the payment details.
//
// |wait_for_updated_details|: It's true when merchant passed in a promise
// into PaymentRequest.show(), so Chrome should disregard the initial payment
// details and show a spinner until the promise resolves with the correct
// payment details. The payment details will be updated with UpdateWith().
// |had_user_activation|: Whether a user activation was consumed with this
// Show() call.
Show(bool wait_for_updated_details, bool had_user_activation);
// Updates the payment details in response to (1) new shipping address or
// shipping option, or (2) the resolution of show()'s PaymentDetailsUpdate
// promise.
// |details|: The details that the merchant provides to update the payment
// request.
UpdateWith(PaymentDetails details);
// Called when the merchant received a new shipping address or shipping
// option, but did not update the payment details in response.
OnPaymentDetailsNotUpdated();
// Requests to abort the checkout in process, for example because the item
// went out of stock.
Abort();
// Closes the payment user interface.
Complete(PaymentComplete result);
// Called when the merchant calls explicitly retry() method in JavaScript.
// The |errors| contains merchant-defined error message strings. They are
// used to indicate to the end-user that something is wrong with the data of
// the payment response.
Retry(PaymentValidationErrors errors);
// Queries whether support for the merchant-specified payment method is
// available, either because the user has a registered payment handler for
// that method, or because the browser can do just-in-time registration for a
// suitable payment handler.
CanMakePayment();
// Queries whether support for the merchant-specified payment method is
// available and the user has an enrolled instrument for that payment method
// that is ready to pay.
HasEnrolledInstrument();
};
Codebase Browser
chromium