Support different amounts per payment method.

This is a proposal for issue w3c#4: Should it be possible to vary amounts depending on payment method.

The goal of this change is to make it simple for web developers in the majority case
when price does not vary by payment method. If a developer wishes to have a different
price for specific payment methods then they include a PaymentDetailsModifier that
includes the new total amount and optionally additional display items that are appended
to the main payment details display items for display. This allows the developer to
explain why the price is different due to a discount or surcharge, for example.

index.html

@@ -399,10 +399,19 @@ <h2>PaymentRequest constructor</h2>
         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.
       </li>
+      <li>
+        If a <a>payment method identifier</a> appears more than once in the <code>methodData</code>
+        or <code>details.modififiers</code> sequences, then <a>throw</a> a <a><code>TypeError</code></a>.
+      </li>
       <li>
         For each <a><code>PaymentMethodData</code></a> in <code>methodData</code>, if the <code>data</code> field
         is supplied but is not a <a>JSON-serializable object</a>, then <a>throw</a> a <a><code>TypeError</code></a>.
       </li>
+      <li>
+        For each <a><code>PaymentDetailsModifier</code></a> in <code>details.modifiers</code>, if the <code>total</code> field
+        is supplied and the first character of <code>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.
+      </li>
       <li>Let <em>request</em> be a new <a><code>PaymentRequest</code></a>.</li>
       <li>
         Store <code>methodData</code> into <em>request</em>@[[\methodData]].
@@ -686,6 +695,7 @@ <h2>PaymentDetails dictionary</h2>
   PaymentItem total;
   sequence&lt;PaymentItem&gt; displayItems;
   sequence&lt;PaymentShippingOption&gt; shippingOptions;
+  sequence&lt;PaymentDetailsModifier&gt; modifiers;
 };
       </pre>
 
@@ -739,6 +749,57 @@ <h2>PaymentDetails dictionary</h2>
         will be fired for this option unless the user selects an alternative option first.
       </p>
     </dd>
+    <dt><code>modifiers</code></dt>
+    <dd>
+      This sequence of <a><code>PaymentDetailsModifier</code></a> dictionaries contains modifiers
+      for particular payment method identifiers. For example, it allows you to adjust the total
+      amount based on payment method.
+    </dd>
+  </dl>
+</section>
+
+<section>
+  <h2>PaymentDetailsModifier dictionary</h2>
+  <pre class="idl">
+    dictionary PaymentDetailsModifier {
+      required sequence&lt;DOMString&gt; supportedMethods;
+      PaymentItem total;
+      sequence&lt;PaymentItem&gt; additionalDisplayItems;
+    };
+  </pre>
+
+  <p>
+    The <code><dfn>PaymentDetailsModifier</dfn></code> dictionary provides details that modify the
+    <a><code>PaymentDetails</code></a> based on <a>payment method identifier</a>. It contains the
+    following fields:
+  </p>
+
+  <dl>
+    <dt><code>supportedMethods</code></dt>
+    <dd>
+      The <code>supportedMethods</code> field contains a sequence of <a>payment method identifiers</a>.
+      The remaining fields in the <a><code>PaymentDetailsModifier</code></a> apply only if the user selects
+      a <a>payment method</a> included in this sequence.
+    </dd>
+    <dt><code>total</code></dt>
+    <dd>
+      This <a><code>PaymentItem</code></a> value overrides the <code>total</code> field in the
+      <a><code>PaymentDetails</code></a> dictionary for the <a>payment method identifiers</a>
+      in the <code>supportedMethods</code> field.
+    </dd>
+    <dt><code>additionalDisplayItems</code></dt>
+    <dd>
+      This sequence of <a><code>PaymentItem</code></a> dictionaries provides additional display
+      items that are appended to the <code>displayItems</code> field in the <a><code>PaymentDetails</code></a>
+      dictionary for the <a>payment method identifiers</a> in the <code>supportedMethods</code>
+      field. This field is commonly used to add a discount or surcharge line item indicating the
+      reason for the different <code>total</code> amount for the selected <a>payment method</a>
+      that the user agent MAY display.
+      <p>
+      The user agent MAY validate that the <code>total</code> amount is the sum of the <code>displayItems</code>
+      and the <code>additionalDisplayItems</code>, but it is the responsibility of the calling code to ensure that.
+      </p>
+    </dd>
   </dl>
 </section>
 
@@ -921,6 +982,7 @@ <h2>PaymentResponse interface</h2>
 
         interface PaymentResponse {
           readonly attribute DOMString methodName;
+          readonly attribute PaymentCurrencyAmount totalAmount;
           readonly attribute object details;
           readonly attribute PaymentAddress? shippingAddress;
           readonly attribute DOMString? payerEmail;
@@ -940,6 +1002,15 @@ <h2>PaymentResponse interface</h2>
       The <a>payment method identifier</a> for the <a>payment method</a> that the user selected
       to fulfil the transaction.
     </dd>
+    <dt><code>totalAmount</code></dt>
+    <dd>
+      This is the <code>amount</code> value from the <a><code>PaymentItem</code></a> representing
+      the payment request total. This will either be the <code>total.amount</code> value from
+      the <a><code>PaymentDetails</code></a> dictionary for the payment request or it will
+      be the <code>total.amount</code> value from a <a><code>PaymentDetailsModifier</code></a>
+      matching the <a>payment method identifier</a> for the <a>payment method</a> that the user selected
+      to fulfil the transaction.
+    </dd>
     <dt><code><dfn>details</dfn></code></dt>
     <dd>
       A <a>JSON-serializable object</a> that provides a <a>payment method</a> specific message used by the merchant to
@@ -1114,6 +1185,10 @@ <h2>PaymentRequestUpdateEvent</h2>
             If <code>details</code> contains a <code>displayItems</code> value, then copy
             this value to the <code>displayItems</code> field of <em>target</em>@[[\details]].
           </li>
+          <li>
+            If <code>details</code> contains a <code>modifiers</code> value, then copy
+            this value to the <code>modifiers</code> field of <em>target</em>@[[\details]].
+          </li>
           <li>
             If <code>details</code> contains a <code>shippingOptions</code> sequence, then:
             <ol>
@@ -1269,6 +1344,18 @@ <h2>User accepts the payment request algorithm</h2>
         Set the <code>methodName</code> attribute value of <em>response</em> to the <a>payment method identifier</a>
         for the <a>payment method</a> that the user selected to accept the payment.
       </li>
+      <li>
+        Let <em>amount</em> be the <code>total.amount</code> value from <em>request</em>@[[\details]].
+      </li>
+      <li>
+        If there is a <a><code>PaymentDetailsModifier</code></a> <em>modifier</em> in the <code>modifiers</code> sequence
+        in <em>request</em>@[[\details]] that matches the <a>payment method identifier</a> for the
+        <a>payment method</a> that the user selected to accept the payment, then let <em>amount</em>
+        be the <code>total.amount</code> value from <em>modifier</em>.
+      </li>
+      <li>
+        Set the <code>totalAmount</code> attribute value of <em>response</em> to <em>amount</em>.
+      </li>
       <li>
         Set the <code>details</code> attribute value of <em>response</em> to a <a>JSON-serializable object</a>
         containing the <a>payment method</a> specific message used by the merchant to process