teach retry() about payerErrors (#721)

Author: marcoscaceres

index.html

@@ -3165,7 +3165,7 @@ 
           readonly attribute DOMString? payerPhone;
 
           Promise<void> complete(optional PaymentComplete result = "unknown");
-          Promise<void> retry();
+          Promise<void> retry(PaymentValidationErrors errorFields);
         };
       pre>
       <p class="note">
@@ -3177,7 +3177,8 @@ 
           <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>errorFieldsvar>)code> method MUST act as
+          follows:
         p>
         <ol class="algorithm">
           <li>Let <var>responsevar> be the <a>context objecta>.
@@ -3210,8 +3211,12 @@ 
           <li>Set <var>responsevar>.<a>[[\retryPromise]]a> to
           <var>retryPromisevar>.
           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>errorFieldsvar> 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>errorFieldsvar> 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 @@ 
             p>
           li>
         ol>
+        <section data-dfn-for="PaymentValidationErrors" data-link-for=
+        "PaymentValidationErrors">
+          <h3>
+            <dfn>PaymentValidationErrorsdfn> dictionary
+          h3>
+          <pre class="idl">
+            dictionary PaymentValidationErrors {
+              PayerErrorFields payerErrors;
+              AddressErrorFields shippingAddressErrors;
+            };
+          pre>
+          <dl>
+            <dt>
+              <dfn>payerErrorsdfn> member
+            dt>
+            <dd>
+              Validation errors related to the <a>payer detailsa>.
+            dd>
+            <dt>
+              <dfn>shippingAddressErrorsdfn> member
+            dt>
+            <dd data-link-for="PaymentResponse">
+              Represents validation errors with the <a>PaymentResponsea>'s
+              <a>shippingAddressa>.
+            dd>
+          dl>
+        section>
+        <section data-dfn-for="PayerErrorFields" data-link-for=
+        "PayerErrorFields">
+          <h3>
+            <dfn>PayerErrorFieldsdfn> dictionary
+          h3>
+          <pre class="idl">
+          dictionary PayerErrorFields {
+            DOMString payerEmailError;
+            DOMString payerNameError;
+            DOMString payerPhoneError;
+          };
+          pre>
+          <p>
+            The <a>PayerErrorFieldsa> is used to represent validation errors
+            with one or more <a>payer detailsa>.
+          p>
+          <p>
+            <dfn>Payer detailsdfn> are any of the payer's name, payer's phone
+            number, and payer's email.
+          p>
+          <dl data-link-for="PaymentResponse">
+            <dt>
+              <dfn>payerEmailErrordfn> 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>PaymentResponsea>'s
+              <a>payerEmaila> attribute's value.
+            dd>
+            <dt>
+              <dfn>payerNameErrordfn> 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>PaymentResponsea>'s <a>payerNamea>
+              attribute's value.
+            dd>
+            <dt>
+              <dfn>payerPhoneErrordfn> 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>PaymentResponsea>'s
+              <a>payerPhonea> 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>