teach retry() about payerErrors (#721)

Author: marcoscaceres

index.html

@@ -3165,7 +3165,7 @@ <h2>
           readonly attribute DOMString? payerPhone;
 
           Promise&lt;void&gt; complete(optional PaymentComplete result = "unknown");
-          Promise&lt;void&gt; retry();
+          Promise&lt;void&gt; retry(PaymentValidationErrors errorFields);
         };
       </pre>
       <p class="note">
@@ -3177,7 +3177,8 @@ <h2>
           <dfn>retry()</dfn> method
         </h2>
         <p data-tests="payment-response/retry-method-manual.https.html">
-          The <a>retry()</a> method MUST act as follows:
+          The <code>retry(<var>errorFields</var>)</code> method MUST act as
+          follows:
         </p>
         <ol class="algorithm">
           <li>Let <var>response</var> be the <a>context object</a>.
@@ -3210,8 +3211,12 @@ <h2>
           <li>Set <var>response</var>.<a>[[\retryPromise]]</a> to
           <var>retryPromise</var>.
           </li>
-          <li>In the payments UI, indicate to the end-user that something is
-          wrong with the user-provided data of the payment response.
+          <li>By matching the members of <var>errorFields</var> to input fields
+          in the user agent's UI, indicate to the end-user that something is
+          wrong with the data of the payment response. For example, a user
+          agent might draw the user's attention to the erroneous
+          <var>errorFields</var> in the browser's UI and display the value of
+          each field in a manner that helps the user fix each error.
           </li>
           <li data-tests=
           "payment-request/payment-response/rejects_if_not_active-manual.https.html">
@@ -3241,6 +3246,91 @@ <h2>
             </p>
           </li>
         </ol>
+        <section data-dfn-for="PaymentValidationErrors" data-link-for=
+        "PaymentValidationErrors">
+          <h3>
+            <dfn>PaymentValidationErrors</dfn> dictionary
+          </h3>
+          <pre class="idl">
+            dictionary PaymentValidationErrors {
+              PayerErrorFields payerErrors;
+              AddressErrorFields shippingAddressErrors;
+            };
+          </pre>
+          <dl>
+            <dt>
+              <dfn>payerErrors</dfn> member
+            </dt>
+            <dd>
+              Validation errors related to the <a>payer details</a>.
+            </dd>
+            <dt>
+              <dfn>shippingAddressErrors</dfn> member
+            </dt>
+            <dd data-link-for="PaymentResponse">
+              Represents validation errors with the <a>PaymentResponse</a>'s
+              <a>shippingAddress</a>.
+            </dd>
+          </dl>
+        </section>
+        <section data-dfn-for="PayerErrorFields" data-link-for=
+        "PayerErrorFields">
+          <h3>
+            <dfn>PayerErrorFields</dfn> dictionary
+          </h3>
+          <pre class="idl">
+          dictionary PayerErrorFields {
+            DOMString payerEmailError;
+            DOMString payerNameError;
+            DOMString payerPhoneError;
+          };
+          </pre>
+          <p>
+            The <a>PayerErrorFields</a> is used to represent validation errors
+            with one or more <a>payer details</a>.
+          </p>
+          <p>
+            <dfn>Payer details</dfn> are any of the payer's name, payer's phone
+            number, and payer's email.
+          </p>
+          <dl data-link-for="PaymentResponse">
+            <dt>
+              <dfn>payerEmailError</dfn> member
+            </dt>
+            <dd>
+              Denotes that the payer's email suffers from a validation error.
+              In the user agent's UI, this member corresponds to the input
+              field that provided the <a>PaymentResponse</a>'s
+              <a>payerEmail</a> attribute's value.
+            </dd>
+            <dt>
+              <dfn>payerNameError</dfn> member
+            </dt>
+            <dd>
+              Denotes that the payer's name suffers from a validation error. In
+              the user agent's UI, this member corresponds to the input field
+              that provided the <a>PaymentResponse</a>'s <a>payerName</a>
+              attribute's value.
+            </dd>
+            <dt>
+              <dfn>payerPhoneError</dfn> member
+            </dt>
+            <dd>
+              Denotes that the payer's phone number suffers from a validation
+              error. In the user agent's UI, this member corresponds to the
+              input field that provided the <a>PaymentResponse</a>'s
+              <a>payerPhone</a> attribute's value.
+            </dd>
+          </dl>
+          <pre class="example js" title="Payer-related validation errors">
+          const payerErrors = {
+            payerEmailError: "The domain is invalid.",
+            payerPhoneError: "Unknown country code.",
+            payerNameError: "Not in database",
+          };
+          await response.retry({ payerErrors });
+          </pre>
+        </section>
       </section>
       <section>
         <h2>