Allow payment handlers to report back errors via Payment Request API (#1050)

Author: stephenmcgruer

index.html

@@ -1318,10 +1318,11 @@ <h2>
               </p>
             </aside>
             <p>
-              The |acceptPromise| will later be resolved or rejected by either
-              the <a>user accepts the payment request algorithm</a> or the
-              <a>user aborts the payment request algorithm</a>, which are
-              triggered through interaction with the user interface.
+              The |acceptPromise| will later be resolved or rejected by the
+              <a>user accepts the payment request algorithm</a>, or the <a>user
+              aborts the payment request algorithm</a> (which are triggered
+              through interaction with the user interface), or the <a>payment
+              handler indicates an internal error algorithm</a>.
             </p>
             <p data-tests="rejects_if_not_active.https.html">
               If |document| stops being [=Document/fully active=] while the
@@ -2600,9 +2601,10 @@ <h2>
           <li>Return |retryPromise|.
             <p class="note">
               The |retryPromise| will later be resolved by the <a>user accepts
-              the payment request algorithm</a>, or rejected by either the
-              <a>user aborts the payment request algorithm</a> or <a>abort the
-              update</a>.
+              the payment request algorithm</a>, or rejected by the <a>user
+              aborts the payment request algorithm</a>, or <a>abort the
+              update</a>, or the <a>payment handler indicates an internal error
+              algorithm</a>.
             </p>
           </li>
         </ol>
@@ -3947,6 +3949,73 @@ <h2>
           </li>
         </ol>
       </section>
+      <section>
+        <h2>
+          Payment handler indicates an internal error algorithm
+        </h2>
+        <p>
+          The <dfn>payment handler indicates an internal error algorithm</dfn>
+          runs when the <a>payment handler</a> that the user has selected
+          encounters an internal error that prevents it from completing the
+          payment. This can occur due to reasons such as the operating system
+          terminating the payment handler (e.g., due to memory pressure), or
+          the payment handler itself encountering an unrecoverable error.
+        </p>
+        <ol class="algorithm">
+          <li>
+            <a>Queue a task</a> on the <a>user interaction task source</a> to
+            perform the following steps:
+            <ol>
+              <li>Let |request:PaymentRequest| be the {{PaymentRequest}} object
+              that the user is interacting with.
+              </li>
+              <li>If |request|.{{PaymentRequest/[[state]]}} is not
+              "[=PaymentRequest/interactive=]", then terminate this algorithm
+              and take no further action.
+              </li>
+              <li>Let |error| be an {{"OperationError"}} {{DOMException}}.
+              </li>
+              <li>Set |request|.{{PaymentRequest/[[state]]}} to
+              "[=PaymentRequest/closed=]".
+              </li>
+              <li>Set |request|'s <a>payment-relevant browsing context</a>'s
+              <a>payment request is showing</a> boolean to false.
+              </li>
+              <li>Let |response:PaymentResponse| be
+              |request|.{{PaymentRequest/[[response]]}}.
+              </li>
+              <li>If |response| is not null:
+                <ol>
+                  <li>Set |response|.{{PaymentResponse/[[complete]]}} to true.
+                  </li>
+                  <li>Assert: |response|.{{PaymentResponse/[[retryPromise]]}}
+                  is not null.
+                  </li>
+                  <li>Reject |response|.{{PaymentResponse/[[retryPromise]]}}
+                  with |error|.
+                  </li>
+                </ol>
+              </li>
+              <li>Otherwise, reject
+              |request|.{{PaymentRequest/[[acceptPromise]]}} with |error|.
+              </li>
+              <li>Optionally, show a generic error message to the user
+              indicating that the payment could not be completed.
+              </li>
+              <li>Optionally, log detailed error information to the developer
+              console for debugging purposes.
+              </li>
+              <li>Abort the current user interaction and close down any
+              remaining user interface.
+              </li>
+            </ol>
+          </li>
+        </ol>
+        <p class="note">
+          The {{"OperationError"}} type allows merchants to distinguish payment
+          handler errors from user cancellation (which uses {{"AbortError"}}).
+        </p>
+      </section>
       <section>
         <h2>
           Update a <code>PaymentRequest</code>'s details algorithm
@@ -4256,8 +4325,8 @@ <h2>
             {{PaymentRequest}} |request| and <a>exception</a> |exception|:
           </p>
           <ol class="algorithm">
-            <li>Optionally, show an error message to the user when letting them
-            know an error has occurred.
+            <li>Optionally, inform the developer via the console that an error
+            occurred while updating the payment request.
             </li>
             <li>Abort the current user interaction and close down any remaining
             user interface.