From 8f498b8b7e7c6e3bed1cba7d3867dd042e572c5a Mon Sep 17 00:00:00 2001
From: Ade Bateman <bateman@acm.org>
Date: Thu, 15 Sep 2016 21:52:34 -0700
Subject: [PATCH] Add error message that can be provided as part of updateWith

We have had lots of feedback that merchants need to explain errors to
customers during the payment request. For example, if a shipping address
is not acceptable then the site must be able to indicate why.

This change adds an `error` string to the `PaymentDetails`, which may
only be used as part of `updateWith`.
---
 index.html | 18 ++++++++++++++++++
 1 file changed, 18 insertions(+)

diff --git a/index.html b/index.html
index 37f160fe..e06dcc85 100644
--- a/index.html
+++ b/index.html
@@ -386,6 +386,10 @@ <h2>PaymentRequest constructor</h2>
         If <code>details</code> does not contain a value for <code>total</code>, then throw a
         <a><code>TypeError</code></a>.
       </li>
+      <li>
+        If <code>details</code> contains a value for <code>error</code>, then throw a
+        <a><code>TypeError</code></a>.
+      </li>
       <li>
         If the first character of <code>details.total.amount.value</code> is U+002D HYPHEN-MINUS, then throw a
         <a><code>TypeError</code></a>. <code>total</code> MUST be a non-negative amount.
@@ -675,6 +679,7 @@ <h2>PaymentDetails dictionary</h2>
   sequence&lt;PaymentItem&gt; displayItems;
   sequence&lt;PaymentShippingOption&gt; shippingOptions;
   sequence&lt;PaymentDetailsModifier&gt; modifiers;
+  DOMString error;
 };
       </pre>
 
@@ -731,6 +736,15 @@ <h2>PaymentDetails dictionary</h2>
       for particular payment method identifiers. For example, it allows you to adjust the total
       amount based on payment method.
     </dd>
+    <dt><code>error</code></dt>
+    <dd>
+      When the payment request is updated using <a><code>updateWith</code></a>, the <code>PaymentDetails</code>
+      can contain a message in the <code>error</code> field that will be displayed to the user. For example,
+      this might commonly be used to explain why good cannot be shipped to the chosen shipping address.
+      <p>
+        The <code>error</code> field cannot be passed to the <a><code>PaymentRequest</code></a> constructor.
+        Doing so will cause a <a><code>TypeError</code></a> to be thrown. 
+    </dd>
   </dl>
 </section>
 
@@ -1219,6 +1233,10 @@ <h2>updateWith()</h2>
                 </li>
               </ol>
             </li>
+            <li>
+            If <code>details</code> contains an <code>error</code> value, then the <a>user agent</a> should
+            update the user interface to display the error message contained in <code>error</code>.
+            </li>
           </ol>
         </li>
         <li>Set [[\waitForUpdate]] to <em>false</em>.</li>