Fix broken links in Payment API (#31526)

* updateWith method is defined on PaymentRequestUpdateEvent

* PaymentInstrument is a non-standard dictionary

* payerdetailchange event is on PaymentResponse

* PaymentShippingOption is a non-standard dictionary

* PaymentDetailsModifier is a dictionary

* AddressErrors is a dictionary

* the two methods are on PaymentResponse

* remove links of payerdetailchange event

* update details for PaymentDetailsModifier

* add .

* remove mention of PaymentInstrument

* add  {{non-standard_inline}} for shippingAddressErrors & error param of PaymentRequest.show & PaymentRequestUpdateEvent.updateWith

* add {{deprecated_inline}} & {{non-standard_inline}} to `shippingOptions` of PaymentRequest.show & PaymentRequestUpdateEvent.updateWith

* update example of PaymentRequest.paymentmethodchange_event

* fix lint error

* Update files/en-us/web/api/paymentrequestupdateevent/updatewith/index.md

Co-authored-by: Jean-Yves Perrier <[email protected]>

* Update files/en-us/web/api/paymentrequest/show/index.md

Co-authored-by: Jean-Yves Perrier <[email protected]>

* Apply suggestions from code review

Co-authored-by: wbamberg <[email protected]>

* Apply suggestions from code review

* Update files/en-us/web/api/paymentrequestevent/changepaymentmethod/index.md

* Update files/en-us/web/api/paymentrequestupdateevent/updatewith/index.md

---------

Co-authored-by: Jean-Yves Perrier <[email protected]>
Co-authored-by: wbamberg <[email protected]>

files/en-us/web/api/paymentrequest/merchantvalidation_event/index.md

@@ -87,8 +87,6 @@ For more information, see [Merchant validation](/en-US/docs/Web/API/Payment_Requ
 - [Using the Payment Request API](/en-US/docs/Web/API/Payment_Request_API/Using_the_Payment_Request_API)
 - `onmerchantvalidation` event handler property
 - [Merchant validation](/en-US/docs/Web/API/Payment_Request_API/Concepts#merchant_validation)
-- {{domxref("PaymentRequest")}}
-- {{domxref("PaymentRequest.payerdetailchange_event", "payerdetailchange")}} event
 - {{domxref("PaymentRequest.paymentmethodchange_event", "paymentmethodchange")}} event
 - {{domxref("PaymentRequest.shippingaddresschange_event", "shippingaddresschange")}} event
 - {{domxref("PaymentRequest.shippingoptionchange_event", "shippingoptionchange")}} event

files/en-us/web/api/paymentrequest/paymentmethodchange_event/index.md

@@ -43,17 +43,12 @@ _In addition to the properties below, this interface includes properties inherit
 
 Let's take a look at an example. This code creates a new {{domxref("PaymentRequest")}}, adds a handler for the `paymentmethodchange` event by calling the request's {{domxref("EventTarget.addEventListener", "addEventListener()")}}, then calls {{domxref("PaymentRequest.show", "show()")}} to present the payment interface to the user.
 
-The code assumes the existence of a method `detailsForShipping()`, which returns an object containing the shipping options for the `ground` shipping method, in the form found in the {{domxref("PaymentShippingOption")}} dictionary. By doing so, the payment form defaults to the ground shipping method.
+The code assumes the existence of a method `detailsForTransaction()`, which will return an object that can be passed as the [`details`](/en-US/docs/Web/API/PaymentRequest/PaymentRequest#details) argument to the `PaymentRequest` constructor.
 
 ```js
-const options = {
-  requestShipping: true,
-};
-
 const paymentRequest = new PaymentRequest(
   paymentMethods,
-  detailsForShipping("ground"),
-  options,
+  detailsForTransaction(),
 );
 
 paymentRequest.addEventListener(
@@ -85,7 +80,7 @@ handlePaymentChange = (event) => {
 
 This begins by looking at the event's {{domxref("PaymentMethodChangeEvent.methodName", "methodName")}} property; if that indicates that the user is trying to use Apple Pay, we pass the {{domxref("PaymentMethodChangeEvent.methodDetails", "methodDetails")}} into a function called `calculateServiceFee()`, which we might create to take the information about the transaction, such as the underlying credit card being used to service the Apple Pay request, and compute and return an object that specifies changes to be applied to the {{domxref("PaymentRequest")}} in order to add any service fees that the payment method might require.
 
-Before the event handler returns, it calls the event's {{domxref("PaymentMethodChangeEvent.updateWith()")}} method to integrate the changes into the request.
+Before the event handler returns, it calls the event's {{domxref("PaymentRequestUpdateEvent.updateWith()", "updateWith()")}} method to integrate the changes into the request.
 
 ## Specifications
 
@@ -100,6 +95,5 @@ Before the event handler returns, it calls the event's {{domxref("PaymentMethodC
 - [Payment Request API](/en-US/docs/Web/API/Payment_Request_API)
 - [Using the Payment Request API](/en-US/docs/Web/API/Payment_Request_API/Using_the_Payment_Request_API)
 - {{domxref("PaymentRequest.merchantvalidation_event", "merchantvalidation")}} event
-- {{domxref("PaymentRequest.payerdetailchange_event", "payerdetailchange")}} event
 - {{domxref("PaymentRequest.shippingaddresschange_event", "shippingaddresschange")}} event
 - {{domxref("PaymentRequest.shippingoptionchange_event", "shippingoptionchange")}} event

files/en-us/web/api/paymentrequest/show/index.md

@@ -69,14 +69,29 @@ show(detailsPromise)
         - `pending`
           - : A Boolean value which is `true` if the specified `amount` has not yet been finalized. This can be used to show items such as shipping or tax amounts that depend upon the selection of shipping address, shipping option, or so forth. The user agent may show this information but is not required to do so.
 
-    - `error` {{optional_inline}} {{deprecated_inline}}
-      - : A string specifying an error message to present to the user*.* When calling {{domxref("PaymentRequestUpdateEvent.updateWith", "updateWith()")}}, including `error` in the updated data causes the {{Glossary("user agent")}} to display the text as a general error message. For address field specific errors, use `shippingAddressErrors`.
+    - `error` {{optional_inline}} {{deprecated_inline}} {{non-standard_inline}}
+
+      - : A string specifying an error message to present to the user*.* When calling {{domxref("PaymentRequestUpdateEvent.updateWith", "updateWith()")}}, including `error` in the updated data causes the {{Glossary("user agent")}} to display the text as a general error message. For address-field specific errors, use the `shippingAddressErrors` field.
+
     - `modifiers` {{optional_inline}}
-      - : An array of {{domxref("PaymentDetailsModifier")}} objects, each describing a modifier for particular payment method identifiers. For example, you can use one to adjust the total payment amount based on the selected payment method ("5% cash discount!").
-    - `shippingAddressErrors` {{optional_inline}} {{deprecated_inline}}
-      - : An {{domxref("AddressErrors")}} object which includes an error message for each property of the shipping address that could not be validated.
-    - `shippingOptions` {{optional_inline}}
-      - : An array of {{domxref("PaymentShippingOption")}} objects, each describing one available shipping option from which the user may choose.
+
+      - : An array of objects, each describing a modifier for particular payment method identifiers, each with the following properties:
+
+        - `supportedMethods`
+          - : A string that represents the payment method identifier. The payment method identifier only applies if the user selects this payment method.
+        - `total` {{optional_inline}}
+          - : An object that overrides the `total` property of the `detailsPromise` parameter if this payment method is selected by the user. The property takes the same input with the `total` property of the `detailsPromise` parameter.
+        - `additionalDisplayItems` {{optional_inline}}
+          - : An {{jsxref("Array")}} of objects provide additional display items that are appended to the `displayItems` property of the `detailsPromise` parameter if this payment method is selected by the user. This property is commonly used to add a discount or surcharge line item indicating the reason for the different total amount for the selected payment method that the user agent may display. The property takes the same input with the `displayItems` property of the `detailsPromise` parameter.
+        - `data` {{optional_inline}}
+          - : A serializable object that provides optional information that might be needed by the supported payment methods.
+
+        For example, you can use one to adjust the total payment amount based on the selected payment method ("5% cash discount!").
+
+    - `shippingAddressErrors` {{optional_inline}} {{deprecated_inline}} {{non-standard_inline}}
+      - : An object which includes an error message for each property of the shipping address that could not be validated.
+    - `shippingOptions` {{optional_inline}} {{deprecated_inline}} {{non-standard_inline}}
+      - : An array of objects, each describing one available shipping option from which the user may choose.
     - `total` {{optional_inline}}
       - : An object with the same properties as the objects in `displayItems` providing an updated total for the payment. Make sure this equals the sum of all of the items in `displayItems`. _This is not calculated automatically_. You must update this value yourself anytime the total amount due changes. This lets you have flexibility for how to handle things like tax, discounts, and other adjustments to the total price charged.
 
@@ -316,6 +331,6 @@ document.getElementById("buyButton").onclick = requestPayment;
 - [Payment Request API](/en-US/docs/Web/API/Payment_Request_API)
 - [Using the Payment Request API](/en-US/docs/Web/API/Payment_Request_API/Using_the_Payment_Request_API)
 - {{domxref('PaymentRequest.abort()')}}
-- {{domxref("PaymentRequest.retry()")}}
-- {{domxref("PaymentRequest.complete()")}}
 - {{domxref("PaymentResponse")}}
+- {{domxref("PaymentResponse.retry()")}}
+- {{domxref("PaymentResponse.complete()")}}

files/en-us/web/api/paymentrequestevent/changepaymentmethod/index.md

@@ -37,7 +37,9 @@ A {{jsxref("Promise")}} that resolves with a `PaymentRequestDetailsUpdate` objec
 - `total`
   - : An updated total based on the changed payment method. The total can change, for example, because the billing address of the payment method selected by the user changes the applicable sales tax.
 - `modifiers`
-  - : An array of [`PaymentDetailsModifier`](https://www.w3.org/TR/payment-request/#paymentdetailsmodifier-dictionary) objects.
+
+  - : An {{jsxref("Array")}} of `PaymentDetailsModifier` objects, whose properties are described in {{domxref("PaymentRequestEvent.modifiers")}}.
+
 - `paymentMethodErrors`
   - : An object containing validation errors for the payment method, if any.
 

files/en-us/web/api/paymentrequestevent/index.md

@@ -21,7 +21,7 @@ The **`PaymentRequestEvent`** interface of the {{domxref("Payment Handler API",
 ## Instance properties
 
 - {{domxref("PaymentRequestEvent.instrumentKey","instrumentKey")}} {{ReadOnlyInline}} {{Deprecated_Inline}} {{Non-standard_Inline}}
-  - : Returns a {{domxref("PaymentInstrument")}} object reflecting the payment instrument selected by the user or an empty string if the user has not registered or chosen a payment instrument.
+  - : Returns an object reflecting the payment instrument selected by the user or an empty string if the user has not registered or chosen a payment instrument.
 - {{domxref("PaymentRequestEvent.methodData","methodData")}} {{ReadOnlyInline}} {{Experimental_Inline}}
   - : Returns an array of objects containing payment method identifiers for the payment methods that the website accepts and any associated payment method specific data.
 - {{domxref("PaymentRequestEvent.modifiers","modifiers")}} {{ReadOnlyInline}} {{Experimental_Inline}}

files/en-us/web/api/paymentrequestevent/modifiers/index.md

@@ -11,14 +11,14 @@ browser-compat: api.PaymentRequestEvent.modifiers
 {{SeeCompatTable}}{{APIRef("Payment Handler API")}}
 
 The **`modifiers`** read-only property of the
-{{domxref("PaymentRequestEvent")}} interface returns an array of `PaymentDetailsModifier` objects containing modifiers for payment details.
+{{domxref("PaymentRequestEvent")}} interface returns an {{jsxref("Array")}} of `PaymentDetailsModifier` objects containing modifiers for payment details.
 
 ## Value
 
-An array of `PaymentDetailsModifier` objects containing modifiers for payment details. These objects contain the following properties:
+An array of objects containing modifiers for payment details. These objects contain the following properties:
 
 - `supportedMethods`
-  - : A payment method identifier. The members of the `PaymentDetailsModifier` object only apply to the payment if the user selects this payment method.
+  - : A payment method identifier. The members of the object only apply to the payment if the user selects this payment method.
 - `total`
   - : A `PaymentItem` object containing the following properties:
     - `label`

files/en-us/web/api/paymentrequestupdateevent/paymentrequestupdateevent/index.md

@@ -26,7 +26,7 @@ None.
 
 ### Return value
 
-A new `PaymentRequestUpdateEvent`
+A new `PaymentRequestUpdateEvent`.
 
 ## Specifications
 

files/en-us/web/api/paymentrequestupdateevent/updatewith/index.md

@@ -39,14 +39,20 @@ updateWith(details)
         - `pending`
           - : A Boolean value which is `true` if the specified `amount` has not yet been finalized. This can be used to show items such as shipping or tax amounts that depend upon the selection of shipping address, shipping option, or so forth. The user agent may show this information but is not required to do so.
 
-    - `error` {{optional_inline}} {{deprecated_inline}}
-      - : A string specifying an error message to present to the user*.* When calling `updateWith()`, including `error` in the updated data causes the {{Glossary("user agent")}} to display the text as a general error message. For address field specific errors, use `shippingAddressErrors`.
+    - `error` {{optional_inline}} {{deprecated_inline}} {{non-standard_inline}}
+
+      - : A string specifying an error message to present to the user*.* When calling `updateWith()`, including `error` in the updated data causes the {{Glossary("user agent")}} to display the text as a general error message. For address field-specific errors, use the `shippingAddressErrors` field.
+
     - `modifiers` {{optional_inline}}
-      - : An array of {{domxref("PaymentDetailsModifier")}} objects, each describing a modifier for particular payment method identifiers. For example, you can use one to adjust the total payment amount based on the selected payment method ("5% cash discount!").
-    - `shippingAddressErrors` {{optional_inline}} {{deprecated_inline}}
-      - : An {{domxref("AddressErrors")}} object which includes an error message for each property of the shipping address that could not be validated.
-    - `shippingOptions` {{optional_inline}}
-      - : An array of {{domxref("PaymentShippingOption")}} objects, each describing one available shipping option from which the user may choose.
+
+      - : An {{jsxref("Array")}} of `PaymentDetailsModifier` objects, whose properties are described in {{domxref("PaymentRequestEvent.modifiers")}}.
+
+        For example, you can use one to adjust the total payment amount based on the selected payment method ("5% cash discount!").
+
+    - `shippingAddressErrors` {{optional_inline}} {{deprecated_inline}} {{non-standard_inline}}
+      - : An object which includes an error message for each property of the shipping address that could not be validated.
+    - `shippingOptions` {{optional_inline}} {{deprecated_inline}} {{non-standard_inline}}
+      - : An array of objects, each describing one available shipping option from which the user may choose.
     - `total` {{optional_inline}}
       - : An object with the same properties as the objects in `displayItems` providing an updated total for the payment. Make sure this equals the sum of all of the items in `displayItems`. _This is not calculated automatically_. You must update this value yourself anytime the total amount due changes. This lets you have flexibility for how to handle things like tax, discounts, and other adjustments to the total price charged.