diff --git a/index.html b/index.html index 2984f128..45fc347f 100644 --- a/index.html +++ b/index.html @@ -877,6 +877,9 @@

  • Set |request|.[=PaymentRequest/[[options]]=] to |options|.
    • +
  • Set |request|.[[\requestedShippingAddressParts]] to + |options|.{{PaymentOptions/requestShippingAddressParts}}. +
  • Set |request|.[[\state]] to "created".
  • Set |request|.[[\updating]] to false. @@ -1131,12 +1134,15 @@

  • Pass the [=converted to an IDL value|converted=] second element - in the |paymentMethod| tuple and |modifiers|. Optionally, the - user agent SHOULD send the appropriate data from |request| to the - user-selected payment handler in order to guide the user - through the payment process. This includes the various attributes - and other internal slots of |request| (some MAY be excluded for - privacy reasons where appropriate). + the |paymentMethod| tuple, |modifiers|, + |request|.[[\options]].{{PaymentOptions/requestBillingAddress}} + and + |request|.[[\options]].{{PaymentOptions/requestBillingAddressParts}}. + Optionally, the user agent SHOULD send the appropriate data from + |request| to the user-selected payment handler in order to + guide the user through the payment process. This includes the + various attributes and other internal slots of |request| (some + MAY be excluded for privacy reasons where appropriate).

    Handling of multiple applicable modifiers in the @@ -1486,6 +1492,19 @@

    The PaymentOptions supplied to the constructor. + + + [[\requestedShippingAddressParts]] + + + The current sequence<{{AddressParts}}> specifying + the payee-requested shipping address parts, initially supplied to + the constructor via {{PaymentOptions}}'s + {{PaymentOptions/requestShippingAddressParts}} and then updated + with calls to + {{PaymentRequestUpdateEvent/requestShippingAddress()}}. + + [[\state]] @@ -2016,6 +2035,91 @@

    +
    +

    + AddressParts enum +

    + 
    +        enum AddressParts {
+          "addressLine",
+          "city",
+          "country",
+          "dependentLocality",
+          "organization",
+          "phone",
+          "postalCode",
+          "recipient",
+          "region",
+          "sortingCode"
+        };
+
    +

    + The {{AddressParts}} enum is used to represent individual parts of a + physical address. +

    +
    +
    + "addressLine" +
    +
    + The address line. +
    +
    + "city" +
    +
    + The city. +
    +
    + "country" +
    +
    + The country. +
    +
    + "dependentLocality" +
    +
    + The dependent locality. +
    +
    + "organization" +
    +
    + The organization. +
    +
    + "phone" +
    +
    + The phone number. +
    +
    + "postalCode" +
    +
    + postal code. +
    +
    + "recipient" +
    +
    + The recipient. +
    +
    + "region" +
    +
    + The region. +
    +
    + "sortingCode" +
    +
    + The sorting Code. +
    +
    +

    PaymentShippingType enum @@ -2060,9 +2164,11 @@

    dictionary PaymentOptions { boolean requestPayerName = false; boolean requestBillingAddress = false; + sequence<AddressParts> requestBillingAddressParts = []; boolean requestPayerEmail = false; boolean requestPayerPhone = false; boolean requestShipping = false; + sequence<AddressParts> requestShippingAddressParts = []; PaymentShippingType shippingType = "shipping"; }; @@ -2079,12 +2185,35 @@

    A boolean that indicates whether the user agent SHOULD collect and return the billing address associated with a payment method (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 methodDetails. A merchant + The user agent 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 exposing user - information. + considerations regarding [[[#user-info]]]. + +
    + requestBillingAddressParts member +
    +
    + A sequence of {{AddressParts}} that specifies which fine-grained + parts of the billing address that the payee wishes to receive when + the requestBillingAddress member is true. An empty list means + no restriction, i.e. the payee requests the full billing address. The + requestBillingAddressParts member has no effect if the + requestBillingAddress member is false. +
    requestPayerName member @@ -2118,10 +2247,38 @@

    A boolean that indicates whether the user agent 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 + user agent returns the shipping address in the + {{PaymentRequest}}'s {{PaymentRequest/shippingAddress}} attribute and + the {{PaymentResponse}}'s {{PaymentResponse/shippingAddress}} + attribute. The former is subject to a shipping redact list per + the shipping address changed algorithm. + +
    +
    + requestShippingAddressParts member +
    +
    + A sequence of {{AddressParts}} that specifies which fine-grained + parts of the shipping address that the payee wishes to receive when + the requestShipping member is true. An empty list means no + restriction, i.e. the user agent will return the full shipping + address, subject to the shipping redact list. The + {{PaymentOptions/requestShippingAddressParts}} member has no effect + if the {{PaymentOptions/requestShipping}} member is false. The payee + can request additional pieces incrementally using + {{PaymentRequestUpdateEvent}}'s + {{PaymentRequestUpdateEvent/requestShippingAddress()}}.
    shippingType member @@ -2265,6 +2422,7 @@

    [SecureContext, Exposed=(Window)] interface PaymentAddress { [Default] object toJSON(); + readonly attribute FrozenArray<DOMString> addressLine; readonly attribute DOMString city; readonly attribute DOMString country; readonly attribute DOMString dependentLocality; @@ -2274,7 +2432,6 @@

    readonly attribute DOMString recipient; readonly attribute DOMString region; readonly attribute DOMString sortingCode; - readonly attribute FrozenArray<DOMString> addressLine; };

    @@ -2392,16 +2549,6 @@

    When called, runs [[WEBIDL]]'s default toJSON operation.

    -
    -

    - country attribute -

    -

    - Represents the country of the address. When getting, returns - the value of the {{PaymentAddress}}'s [[\country]] internal - slot. -

    -

    addressLine attribute @@ -2414,21 +2561,21 @@

    - region attribute + city attribute

    - Represents the region of the address. When getting, returns - the value of the {{PaymentAddress}}'s [[\region]] internal + Represents the city of the address. When getting, returns + the value of the {{PaymentAddress}}'s [[\city]] internal slot.

    - city attribute + country attribute

    - Represents the city of the address. When getting, returns - the value of the {{PaymentAddress}}'s [[\city]] internal + Represents the country of the address. When getting, returns + the value of the {{PaymentAddress}}'s [[\country]] internal slot.

    @@ -2444,32 +2591,32 @@

    - postalCode attribute + organization attribute

    -

    - Represents the postal code of the address. When getting, +

    + Represents the organization of the address. When getting, returns the value of the {{PaymentAddress}}'s - [[\postalCode]] internal slot. + [[\organization]] internal slot.

    - sortingCode attribute + phone attribute

    - Represents the sorting code of the address. When getting, - returns the value of the {{PaymentAddress}}'s - [[\sortingCode]] internal slot. + Represents the phone number of the address. When getting, + returns the value of the {{PaymentAddress}}'s [[\phone]] + internal slot.

    - organization attribute + postalCode attribute

    -

    - Represents the organization of the address. When getting, +

    + Represents the postal code of the address. When getting, returns the value of the {{PaymentAddress}}'s - [[\organization]] internal slot. + [[\postalCode]] internal slot.

    @@ -2484,12 +2631,22 @@

    - phone attribute + region attribute +

    +

    + Represents the region of the address. When getting, returns + the value of the {{PaymentAddress}}'s [[\region]] internal + slot. +

    +
    +
    +

    + sortingCode attribute

    - Represents the phone number of the address. When getting, - returns the value of the {{PaymentAddress}}'s [[\phone]] - internal slot. + Represents the sorting code of the address. When getting, + returns the value of the {{PaymentAddress}}'s + [[\sortingCode]] internal slot.

    @@ -2600,16 +2757,16 @@ 

               dictionary AddressInit {
-            DOMString country;
             sequence<DOMString> addressLine;
-            DOMString region;
             DOMString city;
+            DOMString country;
             DOMString dependentLocality;
-            DOMString postalCode;
-            DOMString sortingCode;
             DOMString organization;
-            DOMString recipient;
             DOMString phone;
+            DOMString postalCode;
+            DOMString recipient;
+            DOMString region;
+            DOMString sortingCode;
           };

    @@ -2813,9 +2970,10 @@

    Creating a `PaymentAddress` from user-provided input

    - The steps to create a `PaymentAddress` from - user-provided input are given by the following algorithm. The - algorithm takes a list |redactList|. + The steps to create a `PaymentAddress` from user-provided + input are given by the following algorithm. The algorithm takes + a list |redactList| and a + sequence<{{AddressParts}}> |requestedParts|.

    @@ -2837,26 +2995,30 @@

      +
    1. If |requestedParts| is empty, set it to « "addressLine", "city", + "country", "dependentLocality", "organization", "phone", + "postalCode", "recipient", "region", "sortingCode"». +
    2. Let |details:AddressInit| be an AddressInit dictionary with no members present.
      3. -
    3. If "addressLine" is not in |redactList|, set - |details|["addressLine"] to the result of splitting the - user-provided address line into a list. If none was provided, - set it to the empty list. +
    4. If "addressLine" is in |requestedParts| and is not in + |redactList|, set |details|["addressLine"] to the result of + splitting the user-provided address line into a list. If none + was provided, set it to the empty list.
      5. -
    5. If "country" is not in |redactList|, set - |details|["country"] to the user-provided country as an upper - case [[ISO3166-1]] alpha-2 code, or to the empty string if none was - provided. +
    6. If "country" is in |requestedParts| and is not in |redactList|, + set |details|["country"] to the user-provided country as an + upper case [[ISO3166-1]] alpha-2 code, or to the empty string if none + was provided.
      7. -
    7. If "phone" is not in |redactList|, set |details|["phone"] - to the user-provided phone number, or to the empty string if none was - provided. +
    8. If "phone" is in |requestedParts| and is not in |redactList|, set + |details|["phone"] to the user-provided phone number, or to + the empty string if none was provided.
      9. -
    9. If "city" is not in |redactList|, set |details|["city"] to - the user-provided city, or to the empty string if none was provided. +
    10. If "city" is in |requestedParts| and is not in |redactList|, set + |details|["city"] to the user-provided city, or to the empty + string if none was provided.
      11. -
    11. If "dependentLocality" is not in |redactList|, set - |details|["dependentLocality"] to the user-provided dependent - locality, or to the empty string if none was provided. +
    12. If "dependentLocality" is in |requestedParts| and is not in + |redactList|, set |details|["dependentLocality"] to the + user-provided dependent locality, or to the empty string if none was + provided.
      13. -
    13. If "organization" is not in |redactList|, set - |details|["organization"] to the user-provided recipient - organization, or to the empty string if none was provided. +
    14. If "organization" is in |requestedParts| and is not in + |redactList|, set |details|["organization"] to the + user-provided recipient organization, or to the empty string if none + was provided.
      15. -
    15. If "postalCode" is not in |redactList|, set - |details|["postalCode"] to the user-provided postal code, or - to the empty string if none was provided. Optionally, redact part of - |details|["postalCode"]. +
    16. If "postalCode" is in |requestedParts| and is not in + |redactList|, set |details|["postalCode"] to the user-provided + postal code, or to the empty string if none was provided. Optionally, + redact part of |details|["postalCode"].

      Postal codes in certain countries can be so specific as @@ -2895,13 +3060,13 @@

      17. -
    17. If "recipient" is not in |redactList|, set - |details|["recipient"] to the user-provided recipient of the - transaction, or to the empty string if none was provided. +
    18. If "recipient" is in |requsetedParts| and is not in |redactList|, + set |details|["recipient"] to the user-provided recipient of + the transaction, or to the empty string if none was provided.

    19. - If "region" is not in |redactList|: + If "region" is in |requestedParts| and is not in |redactList|:

      @@ -2922,9 +3087,10 @@

    • -
  • If "sortingCode" is not in |redactList|, set - |details|["sortingCode"] to the user-provided sorting code, or - to the empty string if none was provided. +
  • If "sortingCode" is in |requestedParts| and is not in + |redactList|, set |details|["sortingCode"] to the + user-provided sorting code, or to the empty string if none was + provided.
  • [=PaymentAddress.PaymentAddress()|Internally construct a new `PaymentAddress`=] with |details| and return the result. @@ -3857,8 +4023,30 @@

    constructor(DOMString type, optional PaymentMethodChangeEventInit eventInitDict = {}); readonly attribute DOMString methodName; readonly attribute object? methodDetails; + Promise<object> requestBillingAddress(sequence<AddressParts> addressParts); }; +
    +

    + Constructor +

    +

    + The PaymentMethodChangeEvent(|type|, + |eventInitDict|) constructor MUST act as follows: +

    +
      +
    1. Let |event:PaymentMethodChangeEvent| be the result of calling + the [=Event/constructor=] of {{PaymentMethodChangeEvent}} with + |type| and |eventInitDict|. +
      2. +
    2. Set |event|.[[\waitForMethodDetails]] to false. +
      3. +
    3. Return |event|. +
      4. +
    +

    methodDetails attribute @@ -3879,6 +4067,126 @@

    more information.

    +
    +

    + requestBillingAddress() + method +

    + +

    + The requestBillingAddress(|addressParts|) method MUST act as + follows: +

    +
      +
    1. Let |event:PaymentMethodChangeEvent| be this + {{PaymentMethodChangeEvent}} instance. +
      2. +
    2. Let |request:PaymentRequest| be the value of |event|'s + [=Event/target=]. +
      3. +
    3. Assert: |request| is an instance of {{PaymentRequest}}. +
      4. +
    4. If any of the following is true, then return a promise + rejected with an {{"InvalidStateError"}} {{DOMException}}: + +
      5. +
    5. Set |event|.[[\waitForMethodDetails]] to true. +
      6. +
    6. Let |methodDetailsPromise:Promise| be a new promise. +
      7. +
    7. Return |methodDetailsPromise|, and perform the remaining steps + in parallel. +
      8. +
    8. Let |handler| be the payment handler that triggered this + |event|. +
      9. +
    9. Use a payment handler specific API to send + |addressParts| to |handler| and receive a new object + |methodDetails|. +

      + It is the responsibility of the payment handler to keep track + of successive address parts it is called with and return an + appropriate version of the billing address associated with the + selected payment instrument, potentially with some redact + list applied. +

      +
      10. +
    10. Set |event|.[[\waitForMethodDetails]] to false. +
      11. +
    11. Resolve |methodDetailsPromise| with |methodDetails|. +
      12. +
    +

    @@ -3906,6 +4214,35 @@

    +
    +

    + Internal Slots +

    +

    + Instances of {{PaymentMethodChangeEvent}} are created with the + internal slots in the following table: +

    + + + + + + + + + +
    + Internal Slot + + Description (non-normative) +
    + [[\waitForMethodDetails]] + + A boolean indicating whether there is a pending request for a + method-specific details object initiated by + requestBillingAddress() that has not settled. +
    +
    @@ -3916,6 +4253,7 @@

    [SecureContext, Exposed=Window] interface PaymentRequestUpdateEvent : Event { constructor(DOMString type, optional PaymentRequestUpdateEventInit eventInitDict = {}); + Promise<PaymentAddress> requestShippingAddress(sequence<AddressParts> addressParts); void updateWith(Promise<PaymentDetailsUpdate> detailsPromise); }; @@ -3941,10 +4279,84 @@

  • Set |event|.{{[[waitForUpdate]]}} to false.
    • +
  • Set |event|.[[\waitForShippingAddress]] to false. +
  • Return |event|.
    • +
    +

    + requestShippingAddress() + method +

    + +

    + The requestShippingAddress(|addressParts|) method MUST act + as follows: +

    +
      +
    1. Let |event:PaymentRequestUpdateEvent| be this + {{PaymentRequestUpdateEvent}} instance. +
      2. +
    2. If |event|'s {{ Event/type }} attribute is not + shippingaddresschange, then return a promise rejected + with a {{TypeError}}. +
      3. +
    3. Let |request:PaymentRequest| be the value of |event|'s + [=Event/target=]. +
      4. +
    4. Assert: |request| is an instance of {{PaymentRequest}}. +
      5. +
    5. If any of the following is true, then return a promise + rejected with an {{"InvalidStateError"}} {{DOMException}}: + +
      6. +
    6. Set |event|.[[\waitForShippingAddress]] to true. +
      7. +
    7. Let |addressPromise:Promise| be a new promise. +
      8. +
    8. Return |addressPromise|, and perform the remaining steps in + parallel. +
      9. +
    9. Update |request|.[[\requestedShippingAddressParts]] to + be the union of itself and |addressParts|. +
      10. +
    10. Let |address:PaymentAddress| be the result of create a + `PaymentAddress` from user-provided input with shipping + redact list and + |request|.[[\requestedShippingAddressParts]]. +
      11. +
    11. Set |request|.[=PaymentRequest/shippingAddress=] to |address|. +
      12. +
    12. Set |event|.[[\waitForShippingAddress]] to false. +
      13. +
    13. Resolve |addressPromise| with |address|. +
      14. +
    +

    updateWith() method @@ -4040,7 +4452,7 @@

  • Set |event|.[[\waitForUpdate]] to true.
    • -
  • Let |pmi:URL?| be null. +
  • Let |pmi:URL| be null.
  • If |event| has a methodName attribute, set |pmi| to @@ -4052,6 +4464,14 @@

    • +
    +

    + PaymentRequestUpdateEventInit dictionary +

    + 
    +            dictionary PaymentRequestUpdateEventInit : EventInit {};
+
    +

    Internal Slots @@ -4078,16 +4498,17 @@

    update is currently in progress. + + + [[\waitForShippingAddress]] + + + A boolean indicating whether there is a pending + requestShippingAddress() call that has not settled. + +

    -
    -

    - PaymentRequestUpdateEventInit dictionary -

    - 
    -            dictionary PaymentRequestUpdateEventInit : EventInit {};
-
    -
    @@ -4249,6 +4670,15 @@

    +
    +

    + Shipping redact list +

    +

    + The shipping redact list is a redact list that + includes « "organization", "phone", "recipient", "addressLine" ». +

    +

    Shipping address changed algorithm @@ -4266,32 +4696,10 @@

    Queue a task on the user interaction task source to run the following steps:
      -
    1. -
      -

      - The |redactList| limits the amount of personal information - about the recipient that the API shares with the merchant. -

      -

      - For merchants, the resulting {{PaymentAddress}} object - provides enough information to, for example, calculate - shipping costs, but, in most cases, not enough information - to physically locate and uniquely identify the recipient. -

      -

      - Unfortunately, even with the |redactList|, recipient - anonymity cannot be assured. This is because in some - countries postal codes are so fine-grained that they can - uniquely identify a recipient. -

      -
      -
      2. -
    2. Let |redactList:list| be the empty list. Set |redactList| to - « "organization", "phone", "recipient", "addressLine" ». -
    3. Let |address:PaymentAddress| be the result of running the steps to create a `PaymentAddress` from user-provided - input with |redactList|. + input with shipping redact list and + |request|.[[\requestedShippingAddressParts]].
    4. Set the {{PaymentRequest/shippingAddress}} attribute on |request| to |address|. @@ -4553,7 +4961,8 @@

    5. Let |shippingAddress:PaymentAddress| be the result of create a `PaymentAddress` from user-provided input with - |redactList|. + |redactList| and + |request|.[[\requestedShippingAddressParts]].
    6. Set the {{shippingAddress}} attribute value of |response| to |shippingAddress|. @@ -5196,11 +5605,10 @@

      payment method and might include: