The MerchantValidationEvent interface

1. Extensions to the PaymentRequest interface

WebIDLpartial interface PaymentRequest {
  attribute EventHandler onmerchantvalidation;
};

2. MerchantValidationEvent interface

WebIDL[SecureContext, Exposed=Window]
interface MerchantValidationEvent : Event {
  constructor(DOMString type, optional MerchantValidationEventInit eventInitDict = {});
  readonly attribute DOMString methodName;
  readonly attribute USVString validationURL;
  undefined complete(Promise<any> merchantSessionPromise);
};

WebIDLdictionary MerchantValidationEventInit : EventInit {
  DOMString methodName = "";
  USVString validationURL = "";
};

3. Request merchant validation algorithm

For payment handlers that support merchant validation, the user agent runs the request merchant validation algorithm. The algorithm takes a USVString merchantSpecificURL, provided by the payment handler:

1. Let request be the PaymentRequest object that the user is interacting with.
2. Let validationURL be a absolute-URL string from which a developer can fetch payment handler-specific verification data.
3. Let methodName be the payment method identifier for the payment handler that is requiring merchant validation.
4. Queue a task on the user interaction task source to run the following steps:
   1. Assert: request.[[updating]] is false.
   2. Assert: request.[[state] is "interactive".
   3. Let eventInitDict be an new MerchantValidationEventInit dictionary.
   4. Set eventInitDict.validationURL] to validationURL.
   5. Set eventInitDict.methodName to methodName.
   6. Let event be the result of calling the constructor of MerchantValidationEvent with "merchantvalidation" and eventInitDict.
   7. Initialize event’s isTrusted attribute to true.
   8. Dispatch event to request.

4. Validate merchant's details algorithm

The validate merchant's details algorithm takes a Promise opaqueDataPromise and a PaymentRequest request. The steps are conditional on the opaqueDataPromise settling. If opaqueDataPromise never settles then the payment request is blocked. The user agent SHOULD provide the user with a means to abort a payment request. Implementations MAY choose to implement a timeout for pending updates if opaqueDataPromise doesn't settle in a reasonable amount of time. If an implementation chooses to implement a timeout, they MUST execute the steps listed below in the "upon rejection" path. Such a timeout is a fatal error for the payment request.

1. Set request.[[updating]] to true.
2. In parallel, disable the user interface that allows the user to accept the payment request. This is to ensure that the payment is not accepted until the user interface is updated with any new details.
3. Upon rejection of opaqueDataPromise:
   1. Abort the update with request and an "AbortError" DOMException.
4. Upon fulfillment of opaqueDataPromise with value opaqueData:
   1. Validate the merchant using opaqueData.
   2. If opaqueData is invalid, as per the validation rules of the payment handler, abort the update with request and an appropriate exception and return.
   3. Otherwise, set request.[[updating]] to false.
   4. Enable the user interface, allowing the request for payment to proceed.

5. Privacy considerations

It is important that the validationURL in a MerchantValidationEvent does not expose personally identifying information to unauthorized parties.

7. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, and SHOULD in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.