diff --git a/index.html b/index.html index 59ad5476..a1466b4f 100644 --- a/index.html +++ b/index.html @@ -490,6 +490,39 @@

} +
+

+ Fine-grained error reporting +

+

+ A developer can use the shippingAddressErrors member of the + PaymentDetailsUpdate dictionary to indicate that there are + validation errors with specific attributes of a + PaymentAddress. The shippingAddressErrors member is a + AddressErrorFields dictionary, whose members specifically + demarcate the fields of a physical address that are erroneous + while also providing helpful error messages to be displayed to the + end user. +

+ 
+          request.onshippingaddresschange = ev => {
+            ev.updateWith(validateAddress(request.shippingAddress));
+          };
+          function validateAddress(shippingAddress) {
+            const error = "Can't ship to this address.";
+            const shippingAddressErrors = {
+              cityError: "FarmVille is not a real place.",
+              postalCodeError: "Unknown postal code for your country.",
+            };
+            // Empty shippingOptions implies that we can't ship
+            // to this address.
+            const shippingOptions = [];
+            return { error, shippingAddressErrors, shippingOptions };
+          }
+
+

POSTing payment response back to a server @@ -1713,6 +1746,7 @@

dictionary PaymentDetailsUpdate : PaymentDetailsBase { DOMString error; PaymentItem total; + AddressErrorFields shippingAddressErrors; };

@@ -1756,6 +1790,14 @@

"PaymentCurrencyAmount.value">value is a negative number.

+
+ shippingAddressErrors member +
+
+ Represents validation errors with the shipping address that is + associated with the event + target. +

@@ -2040,7 +2082,7 @@

Physical addresses

- A physical address is composed of the following concepts. + A physical address is composed of the following parts.

@@ -2704,6 +2746,154 @@

+
+

+ AddressErrorFields dictionary +

+ 
+          dictionary AddressErrorFields {
+            DOMString addressLineError;
+            DOMString cityError;
+            DOMString countryError;
+            DOMString dependentLocalityError;
+            DOMString languageCodeError;
+            DOMString organizationError;
+            DOMString phoneError;
+            DOMString postalCodeError;
+            DOMString recipientError;
+            DOMString regionError;
+            DOMString regionCodeError;
+            DOMString sortingCodeError;
+          };
+
+

+ The members of the AddressErrorFields dictionary represent + validation errors with specific parts of a physical address. + Each dictionary member has a dual function: firstly, its presence + denotes that a particular part of an address is suffering from a + validation error. Secondly, the string value allows the developer to + describe the validation error (and possibly how the end user can fix + the error). +

+

+ Developers need to be aware that users might not have the ability to + fix certain parts of an address. As such, they need to be mindful to + not to ask the user to fix things they might not have control over + (e.g., languageCodeError). +

+
+
+ addressLineError member +
+
+ Denotes that the address line has a validation error. In the + user agent's UI, this member corresponds to the input field that + provided the PaymentAddress's addressLine attribute's value. +
+
+ cityError member +
+
+ Denotes that the city has a validation error. In the user + agent's UI, this member corresponds to the input field that + provided the PaymentAddress's city attribute's value. +
+
+ countryError member +
+
+ Denotes that the country has a validation error. In the user + agent's UI, this member corresponds to the input field that + provided the PaymentAddress's country attribute's value. +
+
+ dependentLocalityError member +
+
+ Denotes that the dependent locality has a validation error. + In the user agent's UI, this member corresponds to the input field + that provided the PaymentAddress's dependentLocality attribute's value. +
+
+ languageCodeError member +
+
+ Denotes that the language code has a validation error. In + the user agent's UI, this member corresponds to the input field + that provided the PaymentAddress's languageCode attribute's value. +
+
+ organizationError member +
+
+ Denotes that the organization has a validation error. In the + user agent's UI, this member corresponds to the input field that + provided the PaymentAddress's organization attribute's value. +
+
+ phoneError member +
+
+ Denotes that the phone number has a validation error. In the + user agent's UI, this member corresponds to the input field that + provided the PaymentAddress's phone attribute's value. +
+
+ postalCodeError member +
+
+ Denotes that the postal code has a validation error. In the + user agent's UI, this member corresponds to the input field that + provided the PaymentAddress's postalCode attribute's value. +
+
+ recipientError member +
+
+ Denotes that the recipient has a validation error. In the + user agent's UI, this member corresponds to the input field that + provided the PaymentAddress's addressLine attribute's value. +
+
+ regionError member +
+
+ Denotes that the region has a validation error. In the user + agent's UI, this member corresponds to the input field that + provided the PaymentAddress's region attribute's value. +
+
+ regionCodeError member +
+
+ Denotes that the region code representation of the region + has a validation error. In the user agent's UI, this member + corresponds to the input field that provided the + PaymentAddress's regionCode attribute's value. +
+
+ sortingCodeError member +
+
+ The sorting code has a validation error. In the user agent's + UI, this member corresponds to the input field that provided the + PaymentAddress's sortingCode attribute's value. +
+
+

Creating a PaymentAddress from user-provided input @@ -3914,21 +4104,37 @@

-
  • If request.[[\options]].requestShipping is true, - and - request.[[\details]].shippingOptions - is empty, then the developer has signified that there are no - valid shipping options for the currently-chosen shipping - address (given by request's shippingAddress). In - this case, the user agent SHOULD display an error indicating - this, and MAY indicate that the currently-chosen shipping - address is invalid in some way. The user agent SHOULD use the - error member of - details, if it is present, to give more - information about why there are no valid shipping options for - that address. +
  • +

    + If request.[[\options]].requestShipping is + true, and + request.[[\details]].shippingOptions + is empty, then the developer has signified that there are + no valid shipping options for the currently-chosen + shipping address (given by request's + shippingAddress). +

    +

    + In this case, the user agent SHOULD display an error + indicating this, and MAY indicate that the + currently-chosen shipping address is invalid in some way. + The user agent SHOULD use the error member of + details, if it is present, to give more + information about why there are no valid shipping options + for that address. +

    +

    + Further, if the shippingAddressErrors + member is present, the user agent SHOULD display an error + specifically for each erroneous field of the shipping + address. This is done by matching each present member of + the AddressErrorFields to a corresponding input + field in the shown user interface. +