Skip to content

Commit

Permalink
Straighten out the payment method data flow
Browse files Browse the repository at this point in the history 
This fixes w3c#338 and helps with w3c#307 by stating more explicitly how the data member of PaymentMethodDetails is serialized to a string, stored, and later passed to the appropriate payment app.

Along the way, this fixes w3c#354.

This does not completely fix w3c#307, as the problematic JSON-serializable concept is still used for PaymentDetailsModifier (and is still not used by any part of the processing model; that's w3c#346).
  • Loading branch information
@domenic
domenic committed Dec 14, 2016
1 parent 6eea34d commit 77e3f54
Showing 1 changed file with 89 additions and 60 deletions.
149 changes: 89 additions & 60 deletions index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -125,12 +125,19 @@ <h2>
every transaction: the merchant (e.g., an online web store), the buyer
represented by the <a>user agent</a> (e.g., the user buying from the
online web store), and the <dfn data-lt=
"payment method|payment methods">Payment Method</dfn> (e.g., credit
"payment method|payment methods">payment method</dfn> (e.g., credit
card). Information necessary to process and confirm a transaction is
passed between the <a>Payment Method</a> and the merchant via the
passed between the <a>payment method</a> and the merchant via the
<a>user agent</a> with the buyer confirming and authorizing as
necessary across the flow.
</p>
<p>
The details of how to fulfill a payment request for a given <a>payment
method</a> are handled by <dfn data-lt=
"payment app|payment apps">payment apps</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.
</p>
<p>
In addition to better, more consistent user experiences, this also
enables web sites to take advantage of more secure payment schemes
Expand Down Expand Up @@ -274,13 +281,15 @@ <h2>
</h2>
<p>
The <a>PaymentRequest</a> is constructed using the supplied
<code>methodData</code> list including any <a>payment method</a>
specific <code>data</code>, the payment <code>details</code>, and the
payment <code>options</code>.
<var>methodData</var> list including any <a>payment method</a>
specific <a data-lt="PaymentMethodData.data">data</a>, the payment
<var>details</var>, and the payment <var>options</var>. The
<var>methodData</var> supplied to the <a>PaymentRequest</a>
constructor SHOULD be in the order of preference of the caller.
</p>
<div class="note">
<p>
The <code>methodData</code> sequence contains
The <var>methodData</var> sequence contains
<a>PaymentMethodData</a> dictionaries containing the <a>payment
method identifiers</a> for the <a>payment methods</a> that the web
site accepts and any associated <a>payment method</a> specific
Expand All @@ -303,7 +312,7 @@ <h2>
const request = new PaymentRequest(methodData, details, options);
</pre>
<p>
The <code>details</code> object contains information about the
The <var>details</var> object contains information about the
transaction that the user is being asked to complete such as the
line items in an order.
</p>
Expand All @@ -327,7 +336,7 @@ <h2>
const request = new PaymentRequest(methodData, details, options);
</pre>
<p>
The <code>options</code> object contains information about what
The <var>options</var> object contains information about what
options the web page wishes to use from the payment request system.
</p>
<pre class="example" title="The 'options' argument">
Expand Down Expand Up @@ -359,6 +368,8 @@ <h2>
</li>
</ol>
</li>
<li>Let <var>parsedMethodData</var> be an empty list.
</li>
<li>Process payment methods:
<ol>
<li>If the length of the <var>methodData</var> sequence is zero,
Expand All @@ -374,12 +385,17 @@ <h2>
method</a> needs to include at least one <a>payment method
identifier</a>.
</li>
<li>If the <a data-lt="PaymentMethodData.data">data</a>
member of <var>paymentMethod</var> is present, but
<var>paymentMethod</var>.<a data-lt=
"PaymentMethodData.data">data</a> is not a
<a>JSON-serializable object</a>, then <a>throw</a> a
<a>TypeError</a>.
<li>Let <var>parsedData</var> be the result of
<a>JSON-serializing</a>
<var>paymentMethod</var>.<a data-lt="PaymentMethodData.data">data</a>
into a string, if the <a data-lt=
"PaymentMethodData.data">data</a> member of
<var>paymentMethod</var> is present, or null if it is not.
Rethrow any exceptions.
</li>
<li>Add the tuple (<var>paymentMethod</var>.<a data-lt=
"PaymentMethodData.supportedMethods">supportedMethods</a>,
<var>parsedData</var>) to <var>parsedMethodData</var>.
</li>
</ol>
</li>
Expand Down Expand Up @@ -553,18 +569,8 @@ <h2>
</li>
<li>Set <var>request</var>.<a>[[\details]]</a> to <var>details</var>.
</li>
<li>
<p>
Set <var>request</var>.<a>[[\methodData]]</a> to
<var>methodData</var>.
</p>
<p>
The <var>methodData</var> supplied to the <a>PaymentRequest</a>
constructor SHOULD be in the order of preference of the caller.
Implementations MAY show payment methods in this order if
possible but SHOULD prioritize the preference of the user when
presenting payment methods.
</p>
<li>Set <var>request</var>.<a>[[\parsedMethodData]]</a> to
<var>parsedMethodData</var>.
</li>
<li>Set the value of <var>request</var>'s <a data-lt=
"PaymentRequest.shippingOption">shippingOption</a> attribute to <var>
Expand Down Expand Up @@ -633,22 +639,36 @@ <h2>
<li>Return <var>acceptPromise</var> and perform the remaining steps
<a>in parallel</a>.
</li>
<li>Let <var>supportedMethods</var> be the union of all the
<code>supportedMethods</code> sequences from each
<a>PaymentMethodData</a> in the
<var>request</var>.<a>[[\methodData]]</a> sequence.
</li>
<li>Let <var>acceptedMethods</var> be <var>supportedMethods</var>
with all identifiers removed that the <a>user agent</a> does not
accept.
<li>For each <var>paymentMethod</var> in
<var>request</var>.<a>[[\parsedMethodData]]</a>:
<ol>
<li>Consult the appropriate <a>payment apps</a> to see if they
support any of the <a>payment method identifiers</a> given by the
first element of the <var>paymentMethod</var> tuple, passing
along the data string given by the second element of the tuple in
order to help them determine their support.
</li>
</ol>
</li>
<li>If the length of <var>acceptedMethods</var> is zero, then reject
<var>acceptPromise</var> with a <a>NotSupportedError</a>.
<li>If this consultation produced no supported method of paying, then
reject <var>acceptPromise</var> with a <a>NotSupportedError</a>, and
abort this algorithm.
</li>
<li>Show a user interface to allow the user to interact with the
payment request process. The <var>acceptPromise</var> will later be
resolved by the <a>user accepts the payment request algorithm</a>
through interaction with the user interface.
<li>
<p>
Otherwise, show a user interface to allow the user to interact
with the payment request process, using those <a>payment apps</a>
and <a>payment methods</a> which the above step identified as
feasible. The user agent MAY show payment methods in the order
given by <var>supportedMethods</var>, but SHOULD prioritize the
preference of the user when presenting payment methods and
applications.
</p>
<p>
The <var>acceptPromise</var> will later be resolved by the
<a>user accepts the payment request algorithm</a> through
interaction with the user interface.
</p>
</li>
</ol>
</section>
Expand Down Expand Up @@ -765,10 +785,12 @@ <h2>
</tr>
<tr>
<td>
<dfn>[[\methodData]]</dfn>
<dfn>[[\parsedMethodData]]</dfn>
</td>
<td>
The <code>methodData</code> supplied to the constructor.
The <code>methodData</code> supplied to the constructor, but
represented as tuples containing supported methods and a string
or null for data (instead of the original object form).
</td>
</tr>
<tr>
Expand Down Expand Up @@ -855,9 +877,9 @@ <h2>
<dfn>data</dfn>
</dt>
<dd>
<a data-lt="PaymentMethodData.data">data</a> is a
<a>JSON-serializable object</a> that provides optional information
that might be needed by the supported payment methods.
<a data-lt="PaymentMethodData.data">data</a> is an object that
provides optional information that might be needed by the supported
payment methods. If supplied, it will be <a>JSON-serialized</a>.
</dd>
</dl>
</section>
Expand Down Expand Up @@ -1456,11 +1478,10 @@ <h2>
<dfn>details</dfn>
</dt>
<dd>
A <a>JSON-serializable object</a> that provides a <a>payment
method</a> specific message used by the merchant to process the
transaction and determine successful fund transfer. This data is
returned by the <a>payment method</a> specific code that satisfies
the payment request.
An object that provides a <a>payment method</a> specific message used
by the merchant to process the transaction and determine successful
fund transfer. This data is returned by the <a>payment method</a>
specific code that satisfies the payment request.
</dd>
<dt>
<dfn>shippingAddress</dfn>
Expand Down Expand Up @@ -2027,10 +2048,11 @@ <h2>
<a>payment method</a> that the user selected to accept the payment.
</li>
<li>Set the <code>details</code> attribute value of
<var>response</var> to a <a>JSON-serializable object</a> containing
the <a>payment method</a> specific message that will be used by the
merchant to process the transaction. The format of this response will
be defined for each <a>payment method</a>.
<var>response</var> to an object containing the <a>payment method</a>
specific message that will be used by the merchant to process the
transaction. The format of this response will be defined for each <a>
payment method</a>, and the contents of the response will be
determined by the <a>payment app</a> used.
</li>
<li>If the <code>requestShipping</code> value of
<var>request</var>.<a>[[\options]]</a> is true, then copy the <code>
Expand Down Expand Up @@ -2138,9 +2160,8 @@ <h2>
</dt>
<dd>
The term <dfn data-lt=
"payment method identifier|payment method identifiers">Payment Method
Identifier</dfn> is defined by the Payment Method Identifiers
specification [[!METHOD-IDENTIFIERS]].
"payment method identifier|payment method identifiers">payment method
identifier</dfn> is defined by [[!METHOD-IDENTIFIERS]].
</dd>
<dt>
HTML 5.1
Expand Down Expand Up @@ -2199,9 +2220,17 @@ <h2>
<dfn>JSON.parse</dfn> are defined by [[!ECMA-262-2015]].
<p>
The term <dfn>JSON-serializable object</dfn> used in this
specification means an object that can be serialized to a string
using <a>JSON.stringify</a> and later deserialized back to an
object using <a>JSON.parse</a> with no loss of data.
specification is not well defined; see <a href=
"https://github.com/w3c/browser-payment-api/issues/307">issue
#307</a>.
</p>
<p>
The term <dfn data-lt=
"JSON-serialize|JSON-serialized|JSON-serializing">JSON-serialize</dfn>
applied to a given object means to run the algorithm specified by
the original value of the <a>JSON.stringify</a> function on the
supplied object, passing the supplied object as the sole argument,
and return the resulting string. This can throw an exception.
</p>
</dd>
<dt>
Expand Down

0 comments on commit 77e3f54

Please sign in to comment.