Add support for merchant validation (#751)

marcoscaceres · web-flow · commit 944f5126199a · 2018-08-31T02:18:45.000+10:00
diff --git a/index.html b/index.html
@@ -586,6 +586,7 @@ <h2>
           readonly attribute DOMString? shippingOption;
           readonly attribute PaymentShippingType? shippingType;
 
+          attribute EventHandler onmerchantvalidation;
           attribute EventHandler onshippingaddresschange;
           attribute EventHandler onshippingoptionchange;
           attribute EventHandler onpaymentmethodchange;
@@ -1290,6 +1291,17 @@ <h2>
           "PaymentOptions.shippingType">shippingType</a> member).
         </p>
       </section>
+      <section data-dfn-for="PaymentRequest" data-link-for="PaymentRequest">
+        <h2>
+          <dfn>onmerchantvalidation</dfn> attribute
+        </h2>
+        <p data-tests=
+        "payment-request/onmerchantvalidation-attribute.https.html">
+          A <a>PaymentRequest</a>'s <a>onmerchantvalidation</a> attribute is an
+          <a>EventHandler</a> for a <a>MerchantValidationEvent</a> named
+          "<a>merchantvalidation</a>".
+        </p>
+      </section>
       <section data-dfn-for="PaymentRequest" data-link-for="PaymentRequest">
         <h2>
           <dfn>onshippingaddresschange</dfn> attribute
@@ -3722,6 +3734,21 @@ <h2>
               Target
             </th>
           </tr>
+          <tr>
+            <td>
+              <code><dfn>merchantvalidation</dfn></code>
+            </td>
+            <td>
+              <a>MerchantValidationEvent</a>
+            </td>
+            <td>
+              The user agent requires the merchant to perform merchant
+              validation.
+            </td>
+            <td>
+              <a>PaymentRequest</a>
+            </td>
+          </tr>
           <tr>
             <td>
               <code><dfn>shippingaddresschange</dfn></code>
@@ -3782,6 +3809,166 @@ <h2>
           </tr>
         </table>
       </section>
+      <section data-dfn-for="MerchantValidationEvent" data-link-for=
+      "MerchantValidationEvent">
+        <h2>
+          <dfn>MerchantValidationEvent</dfn> interface
+        </h2>
+        <pre class="idl">
+          [Constructor(DOMString type, optional MerchantValidationEventInit eventInitDict),
+          SecureContext, Exposed=Window]
+          interface MerchantValidationEvent : Event {
+            readonly attribute USVString validationURL;
+            void complete(Promise&lt;any&gt; merchantSessionPromise);
+          };
+        </pre>
+        <section>
+          <h3>
+            <dfn data-lt=
+            "MerchantValidationEvent.MerchantValidationEvent()"><code>MerchantValidationEvent</code>
+            constructor</dfn>
+          </h3>
+          <p data-tests=
+          "MerchantValidationEvent/constructor.https.html, MerchantValidationEvent/constructor.http.html">
+            The <a data-cite="dom#concept-event-constructor-ext">event
+            constructing steps</a>, which take a <a>MerchantValidationEvent</a>
+            <var>event</var>, are as follows:
+          </p>
+          <ol class="algorithm">
+            <li>Let <var>base</var> be the <a data-cite=
+            "dom#context-object">event</a>’s <a data-cite=
+            "!html/multipage/webappapis.html#relevant-settings-object">relevant
+            settings object</a>’s <a data-cite=
+            "!html/multipage/webappapis.html#api-base-url">API base URL</a>.
+            </li>
+            <li>Let <var>input</var> be the empty string.
+            </li>
+            <li>If <var>eventInitDict</var> was passed, set <var>input</var> to
+            the value of <var>eventInitDict</var>["<a>validationURL</a>"].
+            </li>
+            <li data-link-for="MerchantValidationEventInit">Let
+            <var>validationURL</var> be the result of <a data-cite=
+            "!url#concept-url-parser">URL parsing</a> <var>input</var> and
+            <var>base</var>.
+            </li>
+            <li>If <var>validationURL</var> is failure, throw a
+            <a>TypeError</a>.
+            </li>
+            <li>Initialize <var>event</var>.<a>validationURL</a> attribute to
+            <var>validationURL</var>.
+            </li>
+            <li>Initialize <var>event</var>.<a data-lt=
+            "mechvalidation.waitForUpdate">[[\waitForUpdate]]</a> to false.
+            </li>
+          </ol>
+        </section>
+        <section>
+          <h3>
+            <dfn>validationURL</dfn> attribute
+          </h3>
+          <p>
+            A <a data-cite="url#concept-url">URL</a> from which a developer can
+            fetch <a>payment handler</a>-specific verification data. By then
+            passing that data (or a promise that resolves with that data) to
+            <a>complete()</a>, the user agent can verify that the payment
+            request is from a authorized merchant.
+          </p>
+          <p>
+            When getting, returns the value it was <a data-cite=
+            "dom#inner-event-creation-steps">initialized</a> with.
+          </p>
+        </section>
+        <section>
+          <h3>
+            <dfn>complete()</dfn> method
+          </h3>
+          <p data-test=
+          "payment-request/MerchantValidationEvent/complete-method-manual.https.html">
+            The <a>MerchantValidationEvent</a>'s
+            <code>complete(<var>merchantSessionPromise</var>)</code> method
+            MUST act as follows:
+          </p>
+          <ol class="algorithm">
+            <li>Let <var>event</var> be the <a>context object</a>.
+            </li>
+            <li>If <var>event</var>'s <a>isTrusted</a> attribute is false, then
+            <a>throw</a> an "<a>InvalidStateError</a>" <a>DOMException</a>.
+            </li>
+            <li>If <var>event</var>.<a data-lt=
+            "mechvalidation.waitForUpdate">[[\waitForUpdate]]</a> is true, then
+            <a>throw</a> an "<a>InvalidStateError</a>" <a>DOMException</a>.
+            </li>
+            <li>Let <var>request</var> be <var>event</var>'s <a data-cite=
+            "dom#event-target">target</a>.
+            </li>
+            <li>If <var>request</var>.<a>[[\state]]</a> is not
+            "<a>interactive</a>", then <a>throw</a> an
+            "<a>InvalidStateError</a>" <a>DOMException</a>.
+            </li>
+            <li>If <var>request</var>.<a>[[\updating]]</a> is true, then
+            <a>throw</a> an "<a>InvalidStateError</a>" <a>DOMException</a>.
+            </li>
+            <li>Set <var>event</var>'s <a>stop propagation flag</a> and <a>stop
+            immediate propagation flag</a>.
+            </li>
+            <li>Set <var>event</var>.<a data-lt=
+            "mechvalidation.waitForUpdate">[[\waitForUpdate]]</a> to true.
+            </li>
+            <li>Run the <a>validate merchant's details algorithm</a> with <var>
+              merchantSessionPromise</var> and <var>request</var>.
+            </li>
+          </ol>
+        </section>
+        <section>
+          <h2>
+            Internal Slots
+          </h2>
+          <p>
+            Instances of <a>MerchantValidationEvent</a> are created with the
+            internal slots in the following table:
+          </p>
+          <table>
+            <tr>
+              <th>
+                Internal Slot
+              </th>
+              <th>
+                Description (<em>non-normative</em>)
+              </th>
+            </tr>
+            <tr>
+              <td>
+                <dfn data-lt-nodefault="" data-lt=
+                "mechvalidation.waitForUpdate">[[\waitForUpdate]]</dfn>
+              </td>
+              <td>
+                A boolean indicating whether an <a>complete()</a>-initiated
+                update is currently in progress.
+              </td>
+            </tr>
+          </table>
+        </section>
+        <section data-dfn-for="MerchantValidationEventInit" data-link-for=
+        "MerchantValidationEventInit">
+          <h3>
+            <dfn>MerchantValidationEventInit</dfn> dictionary
+          </h3>
+          <pre class="idl">
+            dictionary MerchantValidationEventInit : EventInit {
+              USVString validationURL = "";
+            };
+          </pre>
+          <section>
+            <h4>
+              <dfn>validationURL</dfn> member
+            </h4>
+            <p>
+              A URL from which a developer would fetch <a>payment
+              handler</a>-specific verification data.
+            </p>
+          </section>
+        </section>
+      </section>
       <section data-dfn-for="PaymentMethodChangeEvent" data-link-for=
       "PaymentMethodChangeEvent">
         <h2>
@@ -4032,6 +4219,72 @@ <h2>
         object is set to "<a>interactive</a>", the <a>user agent</a> will
         trigger the following algorithms based on user interaction.
       </p>
+      <section>
+        <h2>
+          Merchant validation
+        </h2>
+        <p>
+          <dfn data-lt="Validate the merchant">Merchant validation</dfn> is the
+          process by which a <a>payment handler</a> validates the identity of a
+          merchant against some <var>value</var> (usually some cryptographic
+          challenge response). Validated merchants are allowed to interface
+          with a <a>payment handler</a>. Details of how actual validation is
+          performed is outside the scope of this specification.
+        </p>
+        <p>
+          It is OPTIONAL for a <a>payment handler</a> to support <a>merchant
+          validation</a>.
+        </p>
+        <p>
+          For <a>payment methods</a> that support <a>merchant validation</a>,
+          the user agent runs the <dfn>request merchant validation
+          algorithm</dfn>. The algorithm takes a <a data-cite=
+          "webidl#idl-USVString"><code>USVString</code></a>
+          <var>merchantSpecificURL</var>, provided by the <a>payment
+          handler</a>:
+        </p>
+        <ol class="algorithm">
+          <li>Let <var>request</var> be the <a>PaymentRequest</a> object that
+          the user is interacting with.
+          </li>
+          <li>Let <var>validationURL</var> be a <a data-cite=
+          "url#absolute-url-string">absolute URL string</a> from which a
+          developer can fetch <a>payment handler</a>-specific verification
+          data.
+          </li>
+          <li>
+            <a>Queue a task</a> on the <a>user interaction task source</a> to
+            run the following steps:
+            <ol>
+              <li>Assert: <var>request</var>.<a>[[\updating]]</a> is false.
+              </li>
+              <li>Assert: <var>request</var>.<a>[[\state]]</a> is
+              "<a>interactive</a>".
+              </li>
+              <li>Let <var>eventInitDict</var> be an new
+              <a>MerchantValidationEventInit</a> dictionary.
+              </li>
+              <li data-link-for="MerchantValidationEventInit">Set
+              <var>eventInitDict</var>["<a>validationURL</a>"] to
+              <var>validationURL</var>.
+              </li>
+              <li>Let <var>event</var> be the result of <a data-cite=
+              "dom#concept-event-constructor">constructing</a> a
+              <a>MerchantValidationEvent</a> with "<a>merchantvalidation</a>"
+              and <var>eventInitDict</var>.
+              </li>
+              <li>Initialize <var>event</var>’s <a data-cite=
+              "dom#dom-event-istrusted"><code>isTrusted</code></a> attribute to
+              true.
+              </li>
+              <li>
+                <a data-cite="dom#concept-event-dispatch">Dispatch</a>
+                <var>event</var> to <var>request</var>.
+              </li>
+            </ol>
+          </li>
+        </ol>
+      </section>
       <section>
         <h2>
           Shipping address changed algorithm
@@ -4821,6 +5074,64 @@ <h2>
           </p>
         </div>
       </section>
+      <section>
+        <h2>
+          Validate merchant's details algorithm
+        </h2>
+        <p>
+          The <dfn>validate merchant's details algorithm</dfn> takes a
+          <a>Promise</a> <var>opaqueDataPromise</var> and a
+          <a>PaymentRequest</a> <var>request</var>. The steps are conditional
+          on the <var>opaqueDataPromise</var> settling. If
+          <var>opaqueDataPromise</var> 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 <var>opaqueDataPromise</var> 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.
+        </p>
+        <ol class="algorithm">
+          <li>Set <var>request</var>.<a>[[\updating]]</a> to true.
+          </li>
+          <li>
+            <a>In parallel</a>, 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.
+          </li>
+          <li>
+            <a>Upon rejection</a> of <var>opaqueDataPromise</var>:
+            <ol>
+              <li>
+                <a>Abort the update</a> with <var>request</var> and an
+                "<a>AbortError</a>" <a>DOMException</a>.
+              </li>
+            </ol>
+          </li>
+          <li>
+            <a>Upon fulfillment</a> of <var>opaqueDataPromise</var> with value
+            <var>opaqueData</var>:
+            <ol>
+              <li>
+                <a>Validate the merchant</a> using <var>opaqueData</var>.
+              </li>
+              <li>If <var>opaqueData</var> is invalid, as per the validation
+              rules of the <a>payment handler</a>, <a>abort the update</a> with
+              <var>request</var> and an appropriate <a data-cite=
+              "!webidl#dfn-exception">exception</a> and return.
+              </li>
+              <li>Otherwise, set <var>request</var>.<a>[[\updating]]</a> to
+              false.
+              </li>
+              <li>Enable the user interface, allowing the request for payment
+              to proceed.
+              </li>
+            </ol>
+          </li>
+        </ol>
+      </section>
     </section>
     <section class="informative">
       <h2>
