- From: Marcos Cáceres <notifications@github.com>
- Date: Tue, 05 Nov 2019 20:59:09 -0800
- To: w3c/payment-request <payment-request@noreply.github.com>
- Cc: Subscribed <subscribed@noreply.github.com>
- Message-ID: <w3c/payment-request/pull/873/review/312159686@github.com>
marcoscaceres requested changes on this pull request.
Couple more suggestions... getting there tho! 💪
> @@ -890,6 +890,8 @@ <h2>
</li>
<li>Set |request|.<a>[[\options]]</a> to |options|.
</li>
+ <li>Set |request|.<a>[[\requestedShippingAddressParts]]</a> to
+ |options|.<a data-lt="PaymentOptions.requestShippingAddressParts">requestShippingAddressParts</a>.
```suggestion
|options|.{{PaymentOptions/requestShippingAddressParts}}.
```
> @@ -2094,12 +2197,34 @@ <h2>
A boolean that indicates whether the <a>user agent</a> SHOULD collect
and return the billing address associated with a <a>payment
method</a> (e.g., the billing address associated with a credit card).
- Typically, the user agent will return the billing address as part of
- the {{PaymentMethodChangeEvent}}'s <a>methodDetails</a>. A merchant
- can use this information to, for example, calculate tax in certain
- jurisdictions and update the displayed total. See below for privacy
- considerations regarding <a href="#user-info">exposing user
- information</a>.
+ The <a>user agent</a> returns the billing address as part of the
+ {{PaymentMethodChangeEvent}}'s {{PaymentMethodChangeEvent/methodDetails}} attribute and the
Nit: hmmm, does the document need a run of tidy?
> @@ -4286,6 +4641,43 @@ <h2>
</li>
</ol>
</section>
+ <section>
+ <h2>
+ <dfn data-lt="shipping-redact-list">
+ Get redact list for shipping address changed algorithm
I don't think we need an algorithm for this (as also implied by how "shipping-redact-list" is used in the rest of the pull request)... the redact list is always the same. Let's just define:
```
The <dfn>shipping redact list</dfn> is a <a>redact list</a> that includes « "organization", "phone", "recipient", "addressLine" ».
```
We can probably also then get rid of the duplicate privacy note?
> @@ -2133,10 +2258,40 @@ <h2>
</dt>
<dd>
A boolean that indicates whether the <a>user agent</a> SHOULD collect
- and return a shipping address as part of the payment request. For
- example, this would be set to true when physical goods need to be
- shipped by the merchant to the user. This would be set to false for
- the purchase of digital goods.
+ and return a shipping address as part of the payment request (e.g.,
+ when physical goods need to be shipped by the payee to the user). The
+ <a>user agent</a> returns the shipping address in the
+ {{PaymentRequest}}'s {{PaymentRequest/shippingAddress}}
+ attribute and the {{PaymentResponse}}'s
+ {{PaymentResponse/shippingAddress}}
+ attribute. The former is subject to a
+ <a data-lt="shipping-redact-list">redact list</a> per the
See comment below about this list...
```suggestion
<a>shipping redact list</a> per the
```
> + <aside class="note">
+ <p>
+ A payee may not need the full shipping address of a user until the
+ payment request is completed. For example, just having "country"
+ may be sufficient to calculate shipping cost. A payee sensitive to
+ the user's privacy can use <a>requestShippingAddressParts</a> to
+ restrict the initial set of address parts returned by the
+ <a>user agent</a>.
+ </p>
+ </aside>
+ </dd>
+ <dt>
+ <dfn>requestShippingAddressParts</dfn> member
+ </dt>
+ <dd>
+ A sequence of <a>AddressParts</a> that specifies which fine-grained
```suggestion
A sequence of {{AddressParts}} that specifies which fine-grained
```
> - information</a>.
+ The <a>user agent</a> returns the billing address as part of the
+ {{PaymentMethodChangeEvent}}'s {{PaymentMethodChangeEvent/methodDetails}} attribute and the
+ {{PaymentResponse}}'s {{PaymentResponse/details}} attribute. A payee can use this
+ information to, for example, calculate tax in certain jurisdictions
+ and update the displayed total. See below for privacy considerations
+ regarding [[[#user-info]]].
+ </dd>
+ <dt>
+ <dfn>requestBillingAddressParts</dfn> member
+ </dt>
+ <dd>
+ A sequence of {{AddressParts}} that specifies which fine-grained
+ parts of the billing address that the payee wishes to receive when the
+ <a>requestBillingAddress</a> member is true. An empty list means no
+ restriction, i.e. the payee requests the full billing address. This
```suggestion
restriction, i.e. the payee requests the full billing address. The <a>requestBillingAddressParts</a>
```
> + The <a>user agent</a> returns the billing address as part of the
+ {{PaymentMethodChangeEvent}}'s {{PaymentMethodChangeEvent/methodDetails}} attribute and the
+ {{PaymentResponse}}'s {{PaymentResponse/details}} attribute. A payee can use this
+ information to, for example, calculate tax in certain jurisdictions
+ and update the displayed total. See below for privacy considerations
+ regarding [[[#user-info]]].
+ </dd>
+ <dt>
+ <dfn>requestBillingAddressParts</dfn> member
+ </dt>
+ <dd>
+ A sequence of {{AddressParts}} that specifies which fine-grained
+ parts of the billing address that the payee wishes to receive when the
+ <a>requestBillingAddress</a> member is true. An empty list means no
+ restriction, i.e. the payee requests the full billing address. This
+ field has no effect if the <a>requestBillingAddress</a> member is
```suggestion
member has no effect if the <a>requestBillingAddress</a> member is
```
> + the user's privacy can use <a>requestShippingAddressParts</a> to
+ restrict the initial set of address parts returned by the
+ <a>user agent</a>.
+ </p>
+ </aside>
+ </dd>
+ <dt>
+ <dfn>requestShippingAddressParts</dfn> member
+ </dt>
+ <dd>
+ A sequence of <a>AddressParts</a> that specifies which fine-grained
+ parts of the shipping address that the payee wishes to receive when
+ the <a>requestShipping</a> member is true. An empty list means no
+ restriction, i.e. the <a>user agent</a> will return the full shipping
+ address, subject to any applicable
+ <a data-lt="shipping-redact-list">redact list</a>. This field has
```suggestion
<a>shipping redact list</a>. This field has
```
> + may be sufficient to calculate shipping cost. A payee sensitive to
+ the user's privacy can use <a>requestShippingAddressParts</a> to
+ restrict the initial set of address parts returned by the
+ <a>user agent</a>.
+ </p>
+ </aside>
+ </dd>
+ <dt>
+ <dfn>requestShippingAddressParts</dfn> member
+ </dt>
+ <dd>
+ A sequence of <a>AddressParts</a> that specifies which fine-grained
+ parts of the shipping address that the payee wishes to receive when
+ the <a>requestShipping</a> member is true. An empty list means no
+ restriction, i.e. the <a>user agent</a> will return the full shipping
+ address, subject to any applicable
```suggestion
address, subject to the
```
> + "city",
+ "country",
+ "dependentLocality",
+ "organization",
+ "phone",
+ "postalCode",
+ "recipient",
+ "region",
+ "sortingCode"
+ };
+ </pre>
+ <p>
+ The {{AddressParts}} enum is used to represent individual parts of a
+ <a>physical address</a>.
+ </p>
+ <dl>
I have a suspicion that some of these might be linking to the IDL definitions instead of the concepts... if they are:
```suggestion
<dl data-link-for="">
```
> @@ -3915,6 +4079,78 @@ <h2>
more information.
</p>
</section>
+ <section>
+ <h2>
+ <dfn data-lt="requestBillingAddress(addressParts)">
+ requestBillingAddress()
+ </dfn> method
+ </h2>
+ <aside class="note">
+ <p>
+ The {{PaymentMethodChangeEvent/requestBillingAddress()}} method allows the
+ developer to incrementally request additional pieces of the
+ billing address that were not initially requested in
+ {{ PaymentOptions.requestBillingAddressParts }}.
+ </p>
+ <pre class="example js" title="how to use `requestBillingAddress()` correctly.">
The nesting makes this a little bit hard to read... suggestion:
```JS
request.onpaymentmethodchange = ev => {
// ✅ Good: request finer-grained address parts inside updateWith()
ev.updateWith(
requestParts(ev, ["country", "postalCode"])
);
};
async function requestParts(ev, parts) {
const methodDetails = await ev.requestBillingAddress(parts);
const newTotal = await getNewTotal(methodDetails);
return newTotal;
}
```
> + follows:
+ </p>
+ <ol class="algorithm">
+ <li>Let |event:PaymentMethodChangeEvent| be this
+ {{PaymentMethodChangeEvent}} instance.
+ </li>
+ <li>If |event|'s {{ Event.isTrusted }} attribute is false, then
+ return <a>a promise rejected with</a> an {{"InvalidStateError"}}
+ {{DOMException}}.
+ </li>
+ <li>Let |request:PaymentRequest| be the value of |event|'s
+ [=Event/target=].
+ </li>
+ <li>Assert: |request| is an instance of {{PaymentRequest}}.
+ </li>
+ <li>If |request|.<a>[[\state]]</a> is not "<a>interactive</a>",
> I think multiple calls should be allowed if they form a promise chain. For example, maybe a merchant wants to iteratively calculate taxes based on country then region.
Right, yes, calling ev.requestBillingAddress() per `.updateWith()`, with multiple `.updateWith()` calls makes sense.. right now it's not clear what one would do in the UI with:
```JS
ev.updateWith((async () => {
const p1 = ev.requestBillingAddress(["country"]);
await new Promise(r => setTimeout(r, 2000));
const p2 = ev.requestBillingAddress(["postcode"]);
await new Promise(r => setTimeout(r, 2000));
const p3 = ev.requestBillingAddress(["city", "state"]);
await Promise.all([p1, p2, p3]);
return someNewTotal();
}));
```
Should calling `ev.requestBillingAddress()` more than once inside `ev.updateWith()` reject? Or should the browser UI just deal with all those?
> +
+ // ❌ Bad - this won't work!
+ request.onshippingaddresschange = (ev) => {
+ // This will throw InvalidStateError since not inside updateWith().
+ ev.requestShippingAddress([]);
+
+ ev.updateWith(getPromiseForNewDetails(ev.target.shippingAddress));
+ };
+ </pre>
+ </aside>
+ <p>
+ The <a>requestShippingAddress(|addressParts|)</a> method MUST act as
+ follows:
+ </p>
+ <ol class="algorithm">
+ <li>Let |event:PaymentRequestUpdateEvent| be this
the `requestShippingAddress()` and `requestBillingAddress()` steps are almost identical. I wonder if we should generalize them to a "request address" algorithm and pass in a /type/ and then "if type is 'billing, do x. If it's 'shipping', do y"?
--
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/873#pullrequestreview-312159686
Received on Wednesday, 6 November 2019 04:59:12 UTC