The MerchantValidationEvent interface

W3C Working Group Note

This version:
Latest published version:
Latest editor's draft:
Test suite:
Marcos Cáceres (W3C Invited Expert)
GitHub w3c/merchant-validation
File a bug
Commit history
Pull requests


Merchant validation is the process by which a payment handler validates the identity of a merchant against some value (usually some cryptographic challenge response). Validated merchants are allowed to interface with a payment handler. Details of how actual validation is performed is outside the scope of this specification.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at


This feature was removed from Payment Request API due to lack of interoperable support. However, as it is implemented by at least one browser engine, the Working Group decided to publish this document as a Working Group Note.

This document was published by the Web Payments Working Group as a First Public Working Group Note.

GitHub Issues are preferred for discussion of this specification.

Publication as a Working Group Note does not imply endorsement by the W3C Membership.

This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 1 August 2017 W3C Patent Policy. The group does not expect this document to become a W3C Recommendation.

This document is governed by the 15 September 2020 W3C Process Document.

1. Extensions to the PaymentRequest interface

WebIDLpartial interface PaymentRequest {
  attribute EventHandler onmerchantvalidation;

1.1 onmerchantvalidation attribute

A PaymentRequest's onmerchantvalidation attribute is an EventHandler for a MerchantValidationEvent named "merchantvalidation".

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);

2.1 Internal Slots

Instances of MerchantValidationEvent are created with the internal slots in the following table:

Internal Slot Description (non-normative)
[[waitForUpdate]] A boolean indicating whether a complete()-initiated update is currently in progress.

2.2 MerchantValidationEvent constructor

The event constructing steps, which take a MerchantValidationEvent event, are as follows:

  1. Let base be the event’s relevant settings object’s api base URL.
  2. Let validationURL be the result of URL parsing eventInitDict.validationURL and base.
  3. If validationURL is failure, throw a TypeError.
  4. Initialize event.validationURL attribute to validationURL.
  5. If eventInitDict.methodName is not the empty string, run the steps to validate a payment method identifier with eventInitDict.methodName. If it returns false, then throw a RangeError exception. Optionally, inform the developer that the payment method identifier is invalid.
  6. Initialize event.methodName attribute to eventInitDict.methodName.
  7. Initialize event.[[waitForUpdate]] to false.

2.3 methodName attribute

When getting, returns the value it was initialized with. See methodName member of MerchantValidationEventInit for more information.

2.4 validationURL attribute

A URL from which a developer can fetch payment handler-specific verification data. By then passing that data (or a promise that resolves with that data) to complete(), the user agent can verify that the payment request is from an authorized merchant.

When getting, returns the value it was initialized with.

2.5 complete() method

The MerchantValidationEvent's complete(merchantSessionPromise) method MUST act as follows:

  1. Let event be this.
  2. If event's isTrusted attribute is false, then throw an "InvalidStateError" DOMException.
  3. If event.[[waitForUpdate]] is true, then throw an "InvalidStateError" DOMException.
  4. Let request be event's target.
  5. If request.[[state] is not "interactive", then throw an "InvalidStateError" DOMException.
  6. If request.[[updating]] is true, then throw an "InvalidStateError" DOMException.
  7. Set event's stop propagation flag and stop immediate propagation flag.
  8. Set event.[[waitForUpdate]] to true.
  9. Run the validate merchant's details algorithm with merchantSessionPromise and request.

2.6 MerchantValidationEventInit dictionary

WebIDLdictionary MerchantValidationEventInit : EventInit {
  DOMString methodName = "";
  USVString validationURL = "";
methodName member
A payment method identifier representing the payment handler that is requiring merchant validation.
validationURL member
A URL from which a developer would fetch payment handler-specific verification data.

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.

6. Events Summary

This section is non-normative.

Event name Interface Dispatched when… Target
merchantvalidation MerchantValidationEvent The user agent requires the merchant to perform merchant validation. PaymentRequest

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.

A. References

A.1 Normative references

DOM Standard. Anne van Kesteren. WHATWG. Living Standard. URL:
HTML Standard. Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL:
Payment Method Identifiers. Marcos Caceres; Domenic Denicola; Zach Koch; Roy McElmurry. W3C. 5 September 2019. W3C Candidate Recommendation. URL:
Payment Request API. Marcos Caceres; Domenic Denicola; Zach Koch; Roy McElmurry; Ian Jacobs; Rouslan Solomakhin. W3C. 12 December 2019. W3C Candidate Recommendation. URL:
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL:
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL:
URL Standard. Anne van Kesteren. WHATWG. Living Standard. URL:
Web IDL. Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: