Re: [w3c/payment-request] editorial: better payment handler integration (#700)

domenic requested changes on this pull request.

Great work to create this layering in general.

> @@ -160,10 +160,24 @@ <h2>
       </ul>
       <p>
         The details of how to fulfill a payment request for a given <a>payment
-        method</a> are handled by <dfn data-lt="payment handler">payment
-        handlers</dfn>. In this specification, these details are left up to the
-        <a>user agent</a>, but future specifications may expand on the
-        processing model in more detail.
+        method</a> is an implementation detail of a <dfn data-lt=
+        "payment handlers">payment handler</dfn>. Additionally, each payment
+        handler defines a <dfn>can make payment</dfn> algorithm. The details of
+        how a payment handler determines wether it, or the user, can

typo "wether"

> @@ -160,10 +160,24 @@ <h2>
       </ul>
       <p>
         The details of how to fulfill a payment request for a given <a>payment
-        method</a> are handled by <dfn data-lt="payment handler">payment
-        handlers</dfn>. In this specification, these details are left up to the
-        <a>user agent</a>, but future specifications may expand on the
-        processing model in more detail.
+        method</a> is an implementation detail of a <dfn data-lt=
+        "payment handlers">payment handler</dfn>. Additionally, each payment

Is this "Additionally," or should it be "Concretely,"? The "can make payment" algorithm seems like a concrete realization of the previous sentence; it doesn't seem like some additional unrelated thing.

> -        method</a> are handled by <dfn data-lt="payment handler">payment
-        handlers</dfn>. In this specification, these details are left up to the
-        <a>user agent</a>, but future specifications may expand on the
-        processing model in more detail.
+        method</a> is an implementation detail of a <dfn data-lt=
+        "payment handlers">payment handler</dfn>. Additionally, each payment
+        handler defines a <dfn>can make payment</dfn> algorithm. The details of
+        how a payment handler determines wether it, or the user, can
+        potentially "make a payment" is also an implementation detail of a
+        payment handler. For an example, see the <a data-cite=
+        "payment-method-basic-card#can-makepayment">can make payment</a>
+        algorithm of [[payment-method-basic-card]].
+      </p>
+      <p>
+        A payment handler also defines the <dfn>steps to respond to a payment
+        request</dfn>, which results with an object, or <a data-cite=

s/results with/returns

"object, or dictionary, that" -> "object or dictionary that"

> -        handlers</dfn>. In this specification, these details are left up to the
-        <a>user agent</a>, but future specifications may expand on the
-        processing model in more detail.
+        method</a> is an implementation detail of a <dfn data-lt=
+        "payment handlers">payment handler</dfn>. Additionally, each payment
+        handler defines a <dfn>can make payment</dfn> algorithm. The details of
+        how a payment handler determines wether it, or the user, can
+        potentially "make a payment" is also an implementation detail of a
+        payment handler. For an example, see the <a data-cite=
+        "payment-method-basic-card#can-makepayment">can make payment</a>
+        algorithm of [[payment-method-basic-card]].
+      </p>
+      <p>
+        A payment handler also defines the <dfn>steps to respond to a payment
+        request</dfn>, which results with an object, or <a data-cite=
+        "!WEBIDL#idl-dictionary">dictionary</a>, that a a merchant uses to

"a a" -> "a"

> -        processing model in more detail.
+        method</a> is an implementation detail of a <dfn data-lt=
+        "payment handlers">payment handler</dfn>. Additionally, each payment
+        handler defines a <dfn>can make payment</dfn> algorithm. The details of
+        how a payment handler determines wether it, or the user, can
+        potentially "make a payment" is also an implementation detail of a
+        payment handler. For an example, see the <a data-cite=
+        "payment-method-basic-card#can-makepayment">can make payment</a>
+        algorithm of [[payment-method-basic-card]].
+      </p>
+      <p>
+        A payment handler also defines the <dfn>steps to respond to a payment
+        request</dfn>, which results with an object, or <a data-cite=
+        "!WEBIDL#idl-dictionary">dictionary</a>, that a a merchant uses to
+        process or validate the transaction. The structure of this object is
+        specific for each <a>payment method</a>. For an example of such an

"specific for" -> "specific to"

> @@ -928,11 +942,23 @@ <h2>
               <var>acceptPromise</var> with that error and terminate this
               algorithm.
               </li>
-              <li>If the user agent has a registered <a>payment handler</a>
-              that supports <var>identifier</var>, then check if the payment
-              handler is authorized and capable of handling the payment request
-              with <var>data</var>. If the check returns in the affirmative,
-              then add payment handler to <var>handlers</var>.
+              <li>Let <var>registeredHandlers</var> be a <a>list</a> of
+              registered <a>payment handlers</a> that are authorized and can
+              handle payment request for <var>identifier</var>.

What is "can handle [a] payment request"? It seems like another algorithm :-/.

Maybe just "registered payment handlers for the payment method _identifier_" or something?

> @@ -928,11 +942,23 @@ <h2>
               <var>acceptPromise</var> with that error and terminate this
               algorithm.
               </li>
-              <li>If the user agent has a registered <a>payment handler</a>
-              that supports <var>identifier</var>, then check if the payment
-              handler is authorized and capable of handling the payment request
-              with <var>data</var>. If the check returns in the affirmative,
-              then add payment handler to <var>handlers</var>.
+              <li>Let <var>registeredHandlers</var> be a <a>list</a> of
+              registered <a>payment handlers</a> that are authorized and can
+              handle payment request for <var>identifier</var>.
+              </li>
+              <li>If <var>registeredHandlers</var> is empty, then continue.
+              </li>

This continue step (and the "Otherwise" on the next line) is unnecessary. You can for each over an empty list with no problem (just like in JS).

> @@ -1143,12 +1169,22 @@ <h2>
               <li>If conversion results in an error, reject <var>promise</var>
               with that error and terminate this algorithm.
               </li>
-              <li>If the user agent has a registered <a>payment handler</a>

Same comments apply to this section.

> -              then resolve <var>promise</var> with true, and abort this
-              algorithm.
+              <li>Let <var>handlers</var> be a <a>list</a> of registered
+              <a>payment handlers</a> that are authorized and can handle
+              payment request for <var>identifier</var>.
+              </li>
+              <li>If <var>handlers</var> is empty, then continue.
+              </li>
+              <li>Otherwise, for each <var>handler</var> in
+              <var>handlers</var>:
+                <ol>
+                  <li>Let <var>canMakePayment</var> be the result of running
+                  <var>handler</var>'s <a>can make payment</a> algorithm with
+                  <var>data</var>.
+                  </li>
+                  <li>If <var>canMakePayment</var> is true, return true.

Resolve promise with true, and return.

-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/payment-request/pull/700#pullrequestreview-116364933