From 869070f2e5a7197be286ddab782747511c83076b Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Thu, 23 Feb 2017 17:46:16 +1100 Subject: [PATCH 1/7] editorial: attr/method intros are notes (closes #379) --- index.html | 91 ++++++++++++++++++++++++++++++++++-------------------- 1 file changed, 57 insertions(+), 34 deletions(-) diff --git a/index.html b/index.html index 106a8eb9..9bc59954 100644 --- a/index.html +++ b/index.html @@ -607,7 +607,7 @@

show() method

-

+

The show() method is called when the page wants to begin user interaction for the payment request. The show() method returns a Promise that will be resolved when the user accepts the @@ -680,23 +680,26 @@

abort() method

-

- The abort() method may be called if the web page wishes to - tell the user agent to abort the payment request - and to tear down any user interface that might be presented. - abort() can only be called after the show() method has - been called and before this instance's [[\acceptPromise]] has - been resolved. For example, a web page might choose to do this if the - goods they are selling are only available for a limited amount of - time. If the user does not accept the payment request within the - allowed time period, then the request will be aborted. -

-

- A user agent might not always be able to abort a request. For - example, if the user agent has delegated responsibility for - the request to another app. In this situation, abort() will - reject the returned Promise. -

+
+

+ The abort() method is called if the web page wishes to tell + the user agent to abort the payment request and + to tear down any user interface that might be shown. The + abort() can only be called after the show() method + has been called (see states) and before this + instance's [[\acceptPromise]] has been resolved. For + example, a web page might choose to do this if the goods they are + selling are only available for a limited amount of time. If the + user does not accept the payment request within the allowed time + period, then the request will be aborted. +

+

+ A user agent might not always be able to abort a request. + For example, if the user agent has delegated responsibility + for the request to another app. In this situation, abort() + will reject the returned Promise. +

+

The abort() method MUST act as follows:

@@ -741,7 +744,7 @@

canMakePayment() method

-

+

The canMakePayment() method can be used by the developer to determine if the PaymentRequest object can be used to make a payment, before they call show(). It returns a Promise @@ -801,28 +804,42 @@

shippingAddress attribute

-

- shippingAddress is populated when the user provides a shipping - address. It is null by default. When a user provides a shipping - address, the shipping address changed algorithm runs. +

+ A PaymentRequest's shippingAddress attribute is + populated when the user provides a shipping address. It is null by + default. When a user provides a shipping address, the shipping + address changed algorithm runs.

+ +
+

+ onshippingaddresschange attribute +

- onshippingaddresschange is an EventHandler - for an Event named shippingaddresschange. + A PaymentRequest's onshippingaddresschange attribute is + an EventHandler for an Event named + shippingaddresschange.

shippingOption attribute

-

- shippingOption is populated when the user chooses a shipping - option. It is null by default. When a user chooses a shipping option, - the shipping option changed algorithm runs. +

+ A PaymentRequest's shippingOption attribute is + populated when the user chooses a shipping option. It is null by + default. When a user chooses a shipping option, the shipping + option changed algorithm runs.

-

- onshippingoptionchange is an EventHandler for - an Event named shippingoptionchange. +

+
+

+ onshippingoptionchange attribute +

+

+ A PaymentRequest's onshippingoptionchange attribute is + an EventHandler for an Event named + shippingoptionchange.

@@ -1757,14 +1774,14 @@

complete() method

-

+

The complete() method is called after the user has accepted the payment request and the [[\acceptPromise]] has been resolved. Calling the complete() method tells the user agent that the transaction is over (and SHOULD cause any remaining user interface to be closed).

-
+

After the payment request has been accepted and the PaymentResponse returned to the page but before the page @@ -1918,6 +1935,12 @@

updateWith() method

+

+ If the web page wishes to update the payment request then it can + call updateWith() and provide a promise that will resolve + with a PaymentDetails dictionary containing changed values + that the user agent presents to the user. +

The updateWith(detailsPromise) method MUST act as follows:

From addedea0b0d2365446149e8019c732165140f1ec Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Thu, 23 Feb 2017 18:10:56 +1100 Subject: [PATCH 2/7] Editorial: note that totals need to be positive --- index.html | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/index.html b/index.html index 9bc59954..a0fd76b9 100644 --- a/index.html +++ b/index.html @@ -1187,6 +1187,11 @@

This PaymentItem contains the non-negative total amount of the payment request. +

+ The total.amount.value can't be a negative number. +

From 7f2e08814a9a2aee6eb87a18ff501510019da1ce Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Mon, 27 Feb 2017 17:27:41 +1100 Subject: [PATCH 3/7] fix: address feedback from @domenic in #438 --- index.html | 43 +++++++++++++++++++++---------------------- 1 file changed, 21 insertions(+), 22 deletions(-) diff --git a/index.html b/index.html index a0fd76b9..23ecd15d 100644 --- a/index.html +++ b/index.html @@ -804,7 +804,7 @@

shippingAddress attribute

-

+

A PaymentRequest's shippingAddress attribute is populated when the user provides a shipping address. It is null by default. When a user provides a shipping address, the shipping @@ -825,7 +825,7 @@

shippingOption attribute

-

+

A PaymentRequest's shippingOption attribute is populated when the user chooses a shipping option. It is null by default. When a user chooses a shipping option, the shipping @@ -1188,9 +1188,10 @@

This PaymentItem contains the non-negative total amount of the payment request.

- The total.amount.value can't be a negative number. + Algorithms in this specification that accept a + PaymentDetails dictionary will throw if the + total.amount.value is a negative number.

@@ -1786,23 +1787,21 @@

agent that the transaction is over (and SHOULD cause any remaining user interface to be closed).

-
-

- After the payment request has been accepted and the - PaymentResponse returned to the page but before the page - calls complete() the payment request user interface remains - in a pending state. At this point the user interface ought not - offer a cancel command because acceptance of the payment request - has been returned. However, if something goes wrong and the page - never calls complete() then the user interface is blocked. -

-

- For this reason, implementations may choose to impose a timeout for - the page to call complete(). If the timeout expires then the - implementation will behave as if complete() was called with - no arguments. -

-
+

+ After the payment request has been accepted and the + PaymentResponse returned to the page but before the page calls + complete() the payment request user interface remains in a + pending state. At this point the user interface ought not offer a + cancel command because acceptance of the payment request has been + returned. However, if something goes wrong and the page never calls + complete() then the user interface is blocked. +

+

+ For this reason, implementations MAY impose a timeout for the page to + call complete(). If the timeout expires then the + implementation will behave as if complete() was called with no + arguments. +

The complete(result) method MUST act as follows:

From 3a18a8d68ff69473257d4928df589f85ba6f8571 Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Tue, 7 Mar 2017 10:23:52 +1100 Subject: [PATCH 4/7] ed: put PaymentResponse attributes into sections (closes #442) --- index.html | 132 +++++++++++++++++++++++++++++++---------------------- 1 file changed, 77 insertions(+), 55 deletions(-) diff --git a/index.html b/index.html index 23ecd15d..b1620aa4 100644 --- a/index.html +++ b/index.html @@ -346,11 +346,11 @@

  • Establish the request's id:
      -
    1. If details.id - is missing, add an id member - to details and set its value to string that uniquely - identifies this payment request. It is RECOMMENDED that the - string be a If details.id is missing, add an id member to details and + set its value to string that uniquely identifies this payment + request. It is RECOMMENDED that the string be a UUID [[!RFC4122]].
    @@ -1189,7 +1189,7 @@

    payment request.

    Algorithms in this specification that accept a - PaymentDetails dictionary will throw if the + PaymentDetailsInit dictionary will throw if the total.amount.value is a negative number.

    @@ -1234,6 +1234,12 @@

    This PaymentItem contains the non-negative total amount. +

    + Algorithms in this specification that accept a + PaymentDetailsUpdate dictionary will throw if the + total.amount.value is a negative number. +

    @@ -1663,7 +1669,7 @@

    -
    +

    PaymentResponse interface

    @@ -1688,94 +1694,110 @@

    A PaymentResponse is returned when a user has selected a payment method and approved a payment request.

    -
    -
    +
    +

    serializer -

    -
    +

    +

    Each attribute is converted to serialized values as per [[!WEBIDL-LS]]. - -

    - methodName -
    -
    +

    +
    +
    +

    + methodName attribute +

    +

    The payment method identifier for the payment method that the user selected to fulfil the transaction. - -

    - details -
    -
    +

    +
    +
    +

    + details attribute +

    +

    An object that provides a payment method specific message used by the merchant to process the transaction and determine successful fund transfer. This data is returned by the payment method specific code that satisfies the payment request. - -

    - shippingAddress -
    -
    +

    +
    +
    +

    + shippingAddress attribute +

    +

    If the requestShipping flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then shippingAddress will be the full and final shipping address chosen by the user. - -

    - shippingOption -
    -
    +

    +
    +
    +

    + shippingOption attribute +

    +

    If the requestShipping flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then shippingOption will be the id attribute of the selected shipping option. - -

    - payerName -
    -
    +

    +
    +
    +

    + payerName attribute +

    +

    If the requestPayerName flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then payerName will be the name provided by the user. - -

    - payerEmail -
    -
    +

    +
    +
    +

    + payerEmail attribute +

    +

    If the requestPayerEmail flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then payerEmail will be the email address chosen by the user. - -

    - payerPhone -
    -
    +

    +
    +
    +

    + payerPhone attribute +

    +

    If the requestPayerPhone flag was set to true in the PaymentOptions passed to the PaymentRequest constructor, then payerPhone will be the phone number chosen by the user. - -

    - requestId -
    -
    +

    +
    +
    +

    + requestId attribute +

    +

    The corresponding payment request id that spawned this payment response. - - +

    +

    complete() method @@ -1942,8 +1964,8 @@

    If the web page wishes to update the payment request then it can call updateWith() and provide a promise that will resolve - with a PaymentDetails dictionary containing changed values - that the user agent presents to the user. + with a PaymentDetailsUpdate dictionary containing changed + values that the user agent presents to the user.

    The updateWith(detailsPromise) method MUST act as follows: From 503d7c9d59094b988eb3b843111eac24dd747b3a Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Tue, 7 Mar 2017 10:47:11 +1100 Subject: [PATCH 5/7] ed: put PaymentAddress' attrs into sections --- index.html | 166 ++++++++++++++++++++++++++++++----------------------- 1 file changed, 94 insertions(+), 72 deletions(-) diff --git a/index.html b/index.html index b1620aa4..2a1c6c70 100644 --- a/index.html +++ b/index.html @@ -1482,104 +1482,126 @@

    readonly attribute DOMString phone; }; -
    -
    +

    + If the requestShipping + flag was set to true in the PaymentOptions passed to the + PaymentRequest constructor, then the user agent will + populate the shippingAddress member of the + PaymentRequest and ultimately the PaymentResponse object + with the user's selected shipping address after the user has accepted + the payment. +

    +
    +

    serializer -

    -
    +

    +

    Each attribute is converted to serialized values as per [[!WEBIDL-LS]]. - -

    - country -
    -
    - This is the [[CLDR]] (Common Locale Data Repository) region code. For +

    +
    +
    +

    + country attribute +

    +

    + This is the [[!CLDR]] (Common Locale Data Repository) region code. For example, US, GB, CN, or JP. - -

    - addressLine -
    -
    +

    +
    +
    +

    + addressLine attribute +

    +

    This is the most specific part of the address. It can include, for example, a street name, a house number, apartment number, a rural delivery route, descriptive instructions, or a post office box number. - -

    - region -
    -
    +

    +
    +
    +

    + region attribute +

    +

    This is the top level administrative subdivision of the country. For example, this can be a state, a province, an oblast, or a prefecture. - -

    - city -
    -
    +

    +
    +
    +

    + city attribute +

    +

    This is the city/town portion of the address. - -

    - dependentLocality -
    -
    +

    +
    +
    +

    + dependentLocality attribute +

    +

    This is the dependent locality or sublocality within a city. For example, used for neighborhoods, boroughs, districts, or UK dependent localities. - -

    - postalCode -
    -
    +

    +
    +
    +

    + postalCode attribute +

    +

    This is the postal code or ZIP code, also known as PIN code in India. - -

    - sortingCode -
    -
    +

    +
    +
    +

    + sortingCode attribute +

    +

    This is the sorting code as used in, for example, France. - -

    - languageCode -
    -
    +

    +
    +
    +

    + languageCode attribute +

    +

    This is the BCP-47 language code for the address. It's used to determine the field separators and the order of fields when formatting the address for display. - -

    - organization -
    -
    +

    +
    +
    +

    + organization attribute +

    +

    This is the organization, firm, company, or institution at this address. - -

    - recipient -
    -
    +

    +
    +
    +

    + recipient attribute +

    +

    This is the name of the recipient or contact person. This member may, under certain circumstances, contain multiline information. For example, it might contain "care of" information. - -

    - phone -
    -
    +

    +
    +
    +

    + phone attribute +

    +

    This is the phone number of the recipient or contact person. - - -

    - If the requestShipping - flag was set to true in the PaymentOptions passed to the - PaymentRequest constructor, then the user agent will - populate the shippingAddress member of the - PaymentRequest and ultimately the PaymentResponse object - with the user's selected shipping address after the user has accepted - the payment. -

    +

    +

    From 5539e1c1177d27da1127264cc382730c6f2f6d30 Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Tue, 7 Mar 2017 10:56:34 +1100 Subject: [PATCH 6/7] minor editorial fixup --- index.html | 19 +++++-------------- 1 file changed, 5 insertions(+), 14 deletions(-) diff --git a/index.html b/index.html index 2a1c6c70..1c044072 100644 --- a/index.html +++ b/index.html @@ -121,7 +121,7 @@

    authorizing as necessary across the flow.

    - The details of how to fulfill a payment request for a given payment + The details of how to fulfil a payment request for a given payment method are handled by payment apps. In this specification, these details are left up to the user agent, but future specifications may expand on the @@ -1482,16 +1482,6 @@

    readonly attribute DOMString phone; }; -

    - If the requestShipping - flag was set to true in the PaymentOptions passed to the - PaymentRequest constructor, then the user agent will - populate the shippingAddress member of the - PaymentRequest and ultimately the PaymentResponse object - with the user's selected shipping address after the user has accepted - the payment. -

    serializer @@ -1507,8 +1497,8 @@

    country attribute

    - This is the [[!CLDR]] (Common Locale Data Repository) region code. For - example, US, GB, CN, or JP. + This is the [[!CLDR]] (Common Locale Data Repository) region code. + For example, US, GB, CN, or JP.

    @@ -1769,7 +1759,8 @@

    true in the PaymentOptions passed to the PaymentRequest constructor, then shippingOption will be the - id attribute of the selected shipping option. + id attribute of the + selected shipping option.

    From 217b760b1e99a0ea3aa36c9ac468fb7427ae32fc Mon Sep 17 00:00:00 2001 From: Marcos Caceres Date: Wed, 8 Mar 2017 14:46:46 +1100 Subject: [PATCH 7/7] ed: fixes based on pull request review --- index.html | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/index.html b/index.html index 1c044072..17c23ecd 100644 --- a/index.html +++ b/index.html @@ -121,7 +121,7 @@

    authorizing as necessary across the flow.

    - The details of how to fulfil a payment request for a given payment + The details of how to fulfill a payment request for a given payment method are handled by payment apps. In this specification, these details are left up to the user agent, but future specifications may expand on the @@ -836,7 +836,7 @@

    onshippingoptionchange attribute

    -

    +

    A PaymentRequest's onshippingoptionchange attribute is an EventHandler for an Event named shippingoptionchange. @@ -1722,7 +1722,7 @@

    The payment method identifier for the payment method - that the user selected to fulfil the transaction. + that the user selected to fulfill the transaction.

    @@ -1962,9 +1962,9 @@

    If the web page wishes to update the payment request then it should - call updateWith() and provide a promise that will resolve with - a PaymentDetailsUpdate dictionary containing changed values - that the user agent SHOULD present to the user. + call updateWith() and provide a PaymentDetailsUpdate + dictionary, or a promise for one, containing changed values that the + user agent SHOULD present to the user.

    The PaymentRequestUpdateEvent constructor MUST set the @@ -1975,10 +1975,10 @@

    updateWith() method

    - If the web page wishes to update the payment request then it can - call updateWith() and provide a promise that will resolve - with a PaymentDetailsUpdate dictionary containing changed - values that the user agent presents to the user. + If the web page wishes to update the payment request then it should + call updateWith() and provide a PaymentDetailsUpdate + dictionary, or a promise for one, containing changed values that + the user agent presents to the user.

    The updateWith(detailsPromise) method MUST act as follows: