Merge branch 'gh-pages' into merchant_validation

marcoscaceres · web-flow · commit e13799fdd258 · 2019-03-14T00:07:45.000+11:00
diff --git a/index.html b/index.html
@@ -222,10 +222,21 @@ <h2>
           <dfn>Steps for when a user changes payment method</dfn> (optional)
         </dt>
         <dd>
-          Steps that describe how to handle the user changing payment method or
-          monetary instrument (e.g., from a debit card to a credit card) that
-          results in a <a data-cite="WEBIDL#idl-dictionary">dictionary</a> or
-          <a data-cite="WEBIDL#idl-object">object</a> or null.
+          <p>
+            Steps that describe how to handle the user changing payment method
+            or monetary instrument (e.g., from a debit card to a credit card)
+            that results in a <a data-cite=
+            "WEBIDL#idl-dictionary">dictionary</a> or <a data-cite=
+            "WEBIDL#idl-object">object</a> or null.
+          </p>
+          <p>
+            A <a>payment handler</a> that defines <a>steps for when a user
+            changes payment method</a> MUST redact the <a>address line</a>, 
+            <a>organization</a>, <a>phone number</a>, and <a>recipient</a>
+            from any <a>PaymentAddress</a> included in the 
+            <a>PaymentMethodChangeEvent</a>'s <a data-link-for=
+            "PaymentMethodChangeEvent">methodDetails</a> attribute.
+          </p>
         </dd>
       </dl>
       <p>
@@ -1375,17 +1386,9 @@ <h2>
           "payment-request/payment-request-canmakepayment-method-protection.https.html">
           Optionally, at the <a>top-level browsing context</a>'s discretion,
           return <a>a promise rejected with</a> a "<a>NotAllowedError</a>" <a>
-            DOMException</a>.
-            <p class="note" data-link-for="PaymentRequest">
-              This allows user agents to apply heuristics to detect and prevent
-              abuse of the <a>canMakePayment()</a> method for fingerprinting
-              purposes, such as creating <a>PaymentRequest</a> objects with a
-              variety of supported <a>payment methods</a> and calling
-              <a>canMakePayment()</a> on them one after the other. For example,
-              a user agent may restrict the number of successful calls that can
-              be made based on the <a>top-level browsing context</a> or the
-              time period in which those calls were made.
-            </p>
+            DOMException</a>. As described in section <a href=
+            "#canmakepayment-protections"></a>, the user agent may limit the
+            rate at which a page can call <a>canMakePayment()</a>.
           </li>
           <li>Let <var>hasHandlerPromise</var> be <a>a new promise</a>.
           </li>
@@ -4338,7 +4341,28 @@ <h2>
             <a>Queue a task</a> on the <a>user interaction task source</a> to
             run the following steps:
             <ol>
-              <li>Let <var>redactList</var> be the empty list. Optionally, set
+              <li>
+                <div class="note" title="Privacy of recipient information">
+                  <p>
+                    The <var>redactList</var> limits the amount of personal
+                    information about the recipient that the API shares with
+                    the merchant.
+                  </p>
+                  <p>
+                    For merchants, the resulting <a>PaymentAddress</a> object
+                    provides enough information to, for example, calculate
+                    shipping costs, but, in most cases, not enough information
+                    to physically locate and uniquely identify the recipient.
+                  </p>
+                  <p>
+                    Unfortunately, even with the <var>redactList</var>,
+                    recipient anonymity cannot be assured. This is because in
+                    some countries postal codes are so fine-grained that they
+                    can uniquely identify a recipient.
+                  </p>
+                </div>
+              </li>
+              <li>Let <var>redactList</var> be the empty list. Set
               <var>redactList</var> to « "organization", "phone", "recipient",
               "addressLine" ».
               </li>
@@ -4398,7 +4422,16 @@ <h2>
           "WEBIDL#idl-object">object</a> or null, and a <var>methodName</var>,
           which is a DOMString that represents the <a>payment method
           identifier</a> of the <a>payment handler</a> the user is interacting
-          with:
+          with.
+        </p>
+        <p class="note" title=
+        "Privacy of information shared by paymentmethodchange event">
+          When the user selects or changes a payment method (e.g., a credit
+          card), the <a>PaymentMethodChangeEvent</a> includes redacted billing
+          address information for the purpose of performing tax calculations.
+          Redacted attributes include, but are not limited to, <a>address
+          line</a>, <a>dependent locality</a>, <a>organization</a>,
+          <a>phone number</a>, and <a>recipient</a>.
         </p>
         <ol class="algorithm">
           <li>Let <var>request</var> be the <a>PaymentRequest</a> object that
@@ -5191,7 +5224,7 @@ <h2>
         </ol>
       </section>
     </section>
-    <section class="informative">
+    <section id="privacy">
       <h2>
         Privacy and Security Considerations
       </h2>
@@ -5271,11 +5304,6 @@ <h2>
           <a>payment method identifier</a>.
         </p>
       </section>
-    </section>
-    <section id="privacy">
-      <h2>
-        Privacy Considerations
-      </h2>
       <section>
         <h2>
           Exposing user information
@@ -5300,6 +5328,13 @@ <h2>
           member with a third-party <a>payment handler</a> without user
           consent.
         </p>
+        <p>
+          Where sharing of privacy-sensitive information might not be obvious
+          to users (e.g., when <a data-lt=
+          "payment method changed algorithm">changing payment methods</a>), it
+          is RECOMMENDED that user agents inform the user of exactly what
+          information is being shared with a merchant.
+        </p>
       </section>
       <section>
         <h2>
@@ -5311,17 +5346,48 @@ <h2>
           <a>validationURL</a> attribute.
         </p>
       </section>
-      <section>
-        <h2>
-          canMakePayment() protections
+        <h2 id="canmakepayment-protections">
+          <code>canMakePayment()</code> protections
         </h2>
         <p data-link-for="PaymentRequest">
-          The <a>canMakePayment()</a> method enables the payee to call
-          <a>show()</a> if the user is ready to take advantage of the API, or
-          to fall back to a legacy checkout experience if not. Because this
-          method shares some information with the payee, user agents are
-          expected to protect the user from abuse of the method, for example,
-          by restricting the number or frequency of calls.
+          The <a>canMakePayment()</a> method enables the payee to determine —
+          before calling <a>show()</a> — whether the user agent knows of any
+          <a>payment handlers</a> available to the user that support the
+          <a>payment methods</a> provided to the <a>PaymentRequest</a>
+          <a data-lt="PaymentRequest.PaymentRequest()">constructor</a>. If no
+          <a>payment handlers</a> support the <a>payment methods</a>, this
+          enables the payee to fall back to a legacy checkout experience.
+          Because this method shares some potentially unique information with
+          the payee, user agents are expected to protect the user from abuse of
+          the method. For example, user agents can reduce user fingerprinting
+          by:
+        </p>
+        <ul data-link-for="PaymentRequest">
+          <li>Allowing the user to configure the user agent to turn off
+          <a>canMakePayment()</a>, which would return <a>a promise rejected
+          with</a> a "<a>NotAllowedError</a>" <a>DOMException</a>.
+          </li>
+          <li>Rate-limiting the frequency of calls to <a>canMakePayment()</a>
+          with different parameters.
+          </li>
+        </ul>
+        <p>
+          For rate-limiting the user agent might look at repeated calls from:
+        </p>
+        <ul>
+          <li>the same effective top-level domain plus one (eTLD+1).
+          </li>
+          <li>the top-level browsing context. Alternatively, the user agent may
+          block access to the API entirely for origins know to be bad actors.
+          </li>
+          <li>the origin of an <a>iframe</a> or popup window.
+          </li>
+        </ul>
+        <p>
+          These rate-limiting techniques intend to increase the cost associated
+          with repeated calls, whether it is the cost of managing multiple
+          eTLDs or the user experience friction of opening multiple windows
+          (tabs or pop-ups).
         </p>
       </section>
     </section>
