The MerchantValidationEvent interface W3C Working Group Note 08 December 2020 This version: https://www.w3.org/TR/2020/NOTE-merchant-validation-20201208/ Latest published version: https://www.w3.org/TR/merchant-validation/ Latest editor's draft: https://w3c.github.io/merchant-validation/ Test suite: https://wpt.live/merchant-validation/ Editor: Marcos Cáceres (W3C Invited Expert) Participate: GitHub w3c/merchant-validation File a bug Commit history Pull requests Copyright © 2020 W3C ® ( MIT , ERCIM , Keio , Beihang ). W3C liability , trademark and permissive document license rules apply. Abstract 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 https://www.w3.org/TR/. Warning 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 . Table of Contents 1. Extensions to the PaymentRequest interface 1.1 onmerchantvalidation attribute 2. MerchantValidationEvent interface 2.1 Internal Slots 2.2 MerchantValidationEvent constructor 2.3 methodName attribute 2.4 validationURL attribute 2.5 complete() method 2.6 MerchantValidationEventInit dictionary 3. Request merchant validation algorithm 4. Validate merchant's details algorithm 5. Privacy considerations 6. Events Summary 7. Conformance A. References A.1 Normative references 1. Extensions to the PaymentRequest interface WebIDL partial 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: Let base be the event ’s relevant settings object ’s api base URL . Let validationURL be the result of URL parsing eventInitDict . validationURL and base . If validationURL is failure, throw a TypeError . Initialize event . validationURL attribute to validationURL . 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. Initialize event . methodName attribute to eventInitDict . methodName . 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: Let event be this . If event 's isTrusted attribute is false, then throw an " InvalidStateError " DOMException . If event . [[waitForUpdate]] is true, then throw an " InvalidStateError " DOMException . Let request be event 's target . If request . [[state] is not "interactive" , then throw an " InvalidStateError " DOMException . If request . [[updating]] is true, then throw an " InvalidStateError " DOMException . Set event 's stop propagation flag and stop immediate propagation flag . Set event . [[waitForUpdate]] to true. Run the validate merchant's details algorithm with merchantSessionPromise and request . 2.6 MerchantValidationEventInit dictionary WebIDL dictionary 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: Let request be the PaymentRequest object that the user is interacting with. Let validationURL be a absolute-URL string from which a developer can fetch payment handler-specific verification data. Let methodName be the payment method identifier for the payment handler that is requiring merchant validation . Queue a task on the user interaction task source to run the following steps: Assert: request . [[updating]] is false. Assert: request . [[state] is "interactive" . Let eventInitDict be an new MerchantValidationEventInit dictionary. Set eventInitDict . validationURL ] to validationURL . Set eventInitDict . methodName to methodName . Let event be the result of calling the constructor of MerchantValidationEvent with " merchantvalidation " and eventInitDict . Initialize event ’s isTrusted attribute to true. 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. Set request . [[updating]] to true. 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. Upon rejection of opaqueDataPromise : Abort the update with request and an " AbortError " DOMException . Upon fulfillment of opaqueDataPromise with value opaqueData : Validate the merchant using opaqueData . If opaqueData is invalid, as per the validation rules of the payment handler, abort the update with request and an appropriate exception and return. Otherwise, set request . [[updating]] to false. 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] DOM Standard . Anne van Kesteren. WHATWG. Living Standard. URL: https://dom.spec.whatwg.org/ [HTML] HTML Standard . Anne van Kesteren; Domenic Denicola; Ian Hickson; Philip Jägenstedt; Simon Pieters. WHATWG. Living Standard. URL: https://html.spec.whatwg.org/multipage/ [payment-method-id] Payment Method Identifiers . Marcos Caceres; Domenic Denicola; Zach Koch; Roy McElmurry. W3C. 5 September 2019. W3C Candidate Recommendation. URL: https://www.w3.org/TR/payment-method-id/ [Payment-Request] Payment Request API . Marcos Caceres; Domenic Denicola; Zach Koch; Roy McElmurry; Ian Jacobs; Rouslan Solomakhin. W3C. 12 December 2019. W3C Candidate Recommendation. URL: https://www.w3.org/TR/payment-request/ [RFC2119] Key words for use in RFCs to Indicate Requirement Levels . S. Bradner. IETF. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119 [RFC8174] Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words . B. Leiba. IETF. May 2017. Best Current Practice. URL: https://tools.ietf.org/html/rfc8174 [url] URL Standard . Anne van Kesteren. WHATWG. Living Standard. URL: https://url.spec.whatwg.org/ [WebIDL] Web IDL . Boris Zbarsky. W3C. 15 December 2016. W3C Editor's Draft. URL: https://heycam.github.io/webidl/ ↑ Permalink exported Referenced in: 2.6 MerchantValidationEventInit dictionary 3. Request merchant validation algorithm (2) 4. Validate merchant's details algorithm Permalink exported IDL Referenced in: 1. Extensions to the PaymentRequest interface 1.1 onmerchantvalidation attribute Permalink exported IDL Referenced in: 1.1 onmerchantvalidation attribute 2. MerchantValidationEvent interface 2.1 Internal Slots 2.2 MerchantValidationEvent constructor 2.5 complete() method 3. Request merchant validation algorithm 5. Privacy considerations 6. Events Summary Permalink exported Referenced in: Not referenced in this document. Permalink Referenced in: 2.2 MerchantValidationEvent constructor 2.5 complete() method (2) Permalink Referenced in: Not referenced in this document. Permalink exported IDL Referenced in: 2. MerchantValidationEvent interface 2.2 MerchantValidationEvent constructor 2.3 methodName attribute Permalink exported IDL Referenced in: 2. MerchantValidationEvent interface 2.2 MerchantValidationEvent constructor 5. Privacy considerations Permalink exported IDL Referenced in: 2. MerchantValidationEvent interface Permalink exported IDL Referenced in: 2. MerchantValidationEvent interface 2.3 methodName attribute 2.6 MerchantValidationEventInit dictionary 3. Request merchant validation algorithm Permalink exported IDL Referenced in: 2.2 MerchantValidationEvent constructor (2) (3) 2.6 MerchantValidationEventInit dictionary 3. Request merchant validation algorithm Permalink exported IDL Referenced in: 2.2 MerchantValidationEvent constructor 2.6 MerchantValidationEventInit dictionary 3. Request merchant validation algorithm Permalink Referenced in: Not referenced in this document. Permalink Referenced in: 2.5 complete() method Permalink Referenced in: 1.1 onmerchantvalidation attribute 3. Request merchant validation algorithm