Skip to content

Commit db50bae

Browse files
Editorial: Define handling of multiple applicable modifiers (w3c#824)
1 parent 5966e82 commit db50bae

File tree

1 file changed

+106
-14
lines changed

1 file changed

+106
-14
lines changed

index.html

Lines changed: 106 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -623,8 +623,6 @@ <h2>
623623
feature, then <a>throw</a> a "<a>SecurityError</a>"
624624
<a>DOMException</a>.
625625
</li>
626-
<li>Let <var>serializedMethodData</var> be an empty list.
627-
</li>
628626
<li>Establish the request's id:
629627
<ol>
630628
<li data-tests="payment-request-id-attribute.https.html">If <var>
@@ -636,6 +634,8 @@ <h2>
636634
</li>
637635
</ol>
638636
</li>
637+
<li>Let <var>serializedMethodData</var> be an empty list.
638+
</li>
639639
<li>Process payment methods:
640640
<ol data-link-for="PaymentMethodData">
641641
<li>If the length of the <var>methodData</var> sequence is zero,
@@ -794,7 +794,9 @@ <h2>
794794
"PaymentDetailsModifier.data">data</a> into a string.
795795
Rethrow any exceptions.
796796
</li>
797-
<li>Add <var>serializedData</var> to
797+
<li>Add the tuple (<var>modifier</var>.<a data-lt=
798+
"PaymentDetailsModifier.supportedMethods">supportedMethods</a>,
799+
<var>serializedData</var>) to
798800
<var>serializedModifierData</var>.
799801
</li>
800802
<li>Remove the <a data-lt="PaymentDetailsModifier.data">
@@ -1055,19 +1057,109 @@ <h2>
10551057
</li>
10561058
</ol>
10571059
</li>
1060+
<li>Let <var>handler</var> be the <a>payment handler</a> selected by
1061+
the end-user.
1062+
</li>
1063+
<li>Let <var>modifiers</var> be an empty list.
1064+
</li>
1065+
<li>For each <var>tuple</var> in <a>[[\serializedModifierData]]</a>:
1066+
<ol>
1067+
<li>If the first element of <var>tuple</var> (a <a>PMI</a>)
1068+
matches the <a>payment method identifier</a> of
1069+
<var>handler</var>, then append the second element of
1070+
<var>tuple</var> (the serialized method data) to
1071+
<var>modifiers</var>.
1072+
</li>
1073+
</ol>
1074+
</li>
10581075
<li>
10591076
<p>
1060-
For the <a>payment handler</a> selected by the end user, the user
1061-
agent MUST pass the <a data-cite=
1077+
Pass the <a data-cite=
10621078
"WEBIDL#dfn-convert-ecmascript-to-idl-value">converted</a> second
1063-
element in the <var>paymentMethod</var> tuple. Optionally, the
1064-
user agent SHOULD send the appropriate data from
1065-
<var>request</var> to the user-selected <a>payment handler</a> in
1066-
order to guide the user through the payment process. This
1067-
includes the various attributes and internal slots of
1068-
<var>request</var> (some MAY be excluded for privacy reasons
1069-
where appropriate).
1079+
element in the <var>paymentMethod</var> tuple and
1080+
<var>modifiers</var>. Optionally, the user agent SHOULD send the
1081+
appropriate data from <var>request</var> to the user-selected
1082+
<a>payment handler</a> in order to guide the user through the
1083+
payment process. This includes the various attributes and other
1084+
internal slots of <var>request</var> (some MAY be excluded for
1085+
privacy reasons where appropriate).
1086+
</p>
1087+
<p>
1088+
Handling of multiple applicable modifiers in the
1089+
<a>[[\serializedModifierData]]</a> internal slot is <a>payment
1090+
handler</a> specific and beyond the scope of this specification.
1091+
Nevertheless, it is RECOMMENDED that <a>payment handlers</a> use
1092+
a "last one wins" approach with items in the
1093+
<a>[[\serializedModifierData]]</a> list: that is to say, an item
1094+
at the end of the list always takes precedence over any item at
1095+
the beginning of the list (see example below).
10701096
</p>
1097+
<aside class="example" title=
1098+
"Handling of multiple applicable modifiers">
1099+
<p>
1100+
This example uses the <a data-cite=
1101+
"payment-method-basic-card">Basic-Card</a> payment method to
1102+
demonstrate precedence order of
1103+
<a>[[\serializedModifierData]]</a>. The first modifier applies
1104+
equally to all cards, irrespective of network. The second
1105+
modifier applies specifically to cards on the "visa" network.
1106+
</p>
1107+
<pre class="js">
1108+
const details = {
1109+
total: {
1110+
label: "Total due",
1111+
amount: { currency: "USD", value: "65.00" },
1112+
},
1113+
};
1114+
// All cards incur a $3.00 processing fee.
1115+
const cardFee = {
1116+
label: "Card processing fee",
1117+
amount: { currency: "USD", value: "3.00" },
1118+
};
1119+
1120+
// But visa card incurs a $1.00 processing fee.
1121+
const visaFee = {
1122+
label: "Visa processing fee",
1123+
amount: { currency: "USD", value: "1.00" },
1124+
};
1125+
1126+
// Modifiers apply when the user chooses to pay with
1127+
// a credit card.
1128+
details.modifiers = [
1129+
// Applies to all cards...
1130+
{
1131+
additionalDisplayItems: [cardFee],
1132+
supportedMethods: "basic-card",
1133+
total: {
1134+
label: "Total due",
1135+
amount: { currency: "USD", value: "53.00" },
1136+
},
1137+
data: {
1138+
supportedNetworks: [], // All networks
1139+
},
1140+
},
1141+
// Applies only to visa cards...
1142+
{
1143+
additionalDisplayItems: [visaFee],
1144+
supportedMethods: "basic-card",
1145+
total: {
1146+
label: "Total due",
1147+
amount: { currency: "USD", value: "51.00" },
1148+
},
1149+
data: {
1150+
supportedNetworks: ["visa"], // Visa network only
1151+
},
1152+
},
1153+
];
1154+
</pre>
1155+
<p>
1156+
If the modifiers array in the example above was to be reversed
1157+
(i.e., <code class="js">supportedNetworks: []</code> was to
1158+
come last in the modifiers list), then it would take precedence
1159+
over the "visa" modifier even though the visa modifier matches
1160+
visa cards more specifically. This is because "last one wins".
1161+
</p>
1162+
</aside>
10711163
<p>
10721164
The <var>acceptPromise</var> will later be resolved or rejected
10731165
by either the <a>user accepts the payment request algorithm</a>
@@ -5185,8 +5277,8 @@ <h2>
51855277
Payment Method Identifiers
51865278
</dt>
51875279
<dd>
5188-
The term <dfn data-lt="payment method identifiers">payment method
5189-
identifier</dfn> is defined by [[payment-method-id]]. It's an unique
5280+
The term <dfn data-lt="PMI">payment method identifier</dfn>, or PMI
5281+
for short, is defined by [[payment-method-id]]. It's an unique
51905282
identifier for a <a>payment method</a>.
51915283
</dd>
51925284
<dt>

0 commit comments

Comments
 (0)