Update payments articles (GoogleChrome#9407)

* Use bobbucks.dev instead of bobpay.xyz.

* Add shipping information back to 'life of a transaction'. Note that show() requires user gesture now.

* Remove identifying parameters from the IS_READY_TO_PAY intent.

* Add back shipping address delegation for Android payment apps

* Remove note about Mozilla implementing PH API, because they have put that work on hold.

* Remove mentions of setting payment instruments. Remove mention of 'coming soon' articles that are not actually in the pipeline.

* Resolve reviewer comments

* Address reviewer comments part 2

Author: rsolomakhin

src/site/content/en/payments/android-payment-apps-delegation/index.md

@@ -147,84 +147,6 @@ class SampleIsReadyToPayService : Service() {
 }
 ```
 
-### Parameters
-
-Pass the following parameters to `onBind` as Intent extras:
-
-* `methodNames`
-* `methodData`
-* `topLevelOrigin`
-* `topLevelCertificateChain`
-* `topLevelCertificateChain`
-* `paymentRequestOrigin`
-
-```kotlin
-override fun onBind(intent: Intent?): IBinder? {
-  val extras: Bundle? = intent?.extras
-  // …
-}
-```
-
-#### `methodNames`
-
-The names of the methods being queried. The elements are the keys in the
-`methodData` dictionary, and indicate the methods that the payment app supports.
-
-```kotlin
-val methodNames: List<String>? = extras.getStringArrayList("methodNames")
-```
-
-#### `methodData`
-
-A mapping from each entry of `methodNames` to the
-[`methodData`](https://w3c.github.io/payment-request/#declaring-multiple-ways-of-paying).
-
-```kotlin
-val methodData: Bundle? = extras.getBundle("methodData")
-```
-
-#### `topLevelOrigin`
-
-The merchant's origin without the scheme (the scheme-less origin of the
-top-level browsing context). For example, `https://mystore.com/checkout` will be
-passed as `mystore.com`.
-
-```kotlin
-val topLevelOrigin: String? = extras.getString("topLevelOrigin")
-```
-
-#### `topLevelCertificateChain`
-
-The merchant's certificate chain (the certificate chain of the top-level
-browsing context). Null for localhost and file on disk, which are both secure
-contexts without SSL certificates. The certificate chain is necessary because a
-payment app might have different trust requirements for websites.
-
-```kotlin
-val topLevelCertificateChain: Array<Parcelable>? =
-    extras.getParcelableArray("topLevelCertificateChain")
-```
-
-Each `Parcelable` is a `Bundle` with a `"certificate"` key and a byte array
-value.
-
-```kotlin
-val list: List<ByteArray>? = topLevelCertificateChain?.mapNotNull { p ->
-  (p as Bundle).getByteArray("certificate")
-}
-```
-
-#### `paymentRequestOrigin`
-
-The schemeless origin of the iframe browsing context that invoked the `new
-PaymentRequest(methodData, details, options)` constructor in JavaScript. If the
-constructor was invoked from the top-level context, then the value of this
-parameter equals the value of `topLevelOrigin` parameter.
-
-```kotlin
-val paymentRequestOrigin: String? = extras.getString("paymentRequestOrigin")
-```
-
 ### Response
 
 The service can send its response via `handleIsReadyToPay(Boolean)` method.
@@ -280,7 +202,7 @@ To support multiple payment methods, add a `<meta-data>` tag with a
 
   <meta-data
     android:name="org.chromium.default_payment_method_name"
-    android:value="https://bobpay.xyz/pay" />
+    android:value="https://bobbucks.dev/pay" />
   <meta-data
     android:name="org.chromium.payment_method_names"
     android:resource="@array/method_names" />
@@ -415,7 +337,7 @@ The activity can send its response back through `setResult` with `RESULT_OK`.
 
 ```kotlin
 setResult(Activity.RESULT_OK, Intent().apply {
-  putExtra("methodName", "https://bobpay.xyz/pay")
+  putExtra("methodName", "https://bobbucks.dev/pay")
   putExtra("details", "{\"token\": \"put-some-data-here\"}")
 })
 finish()

src/site/content/en/payments/android-payment-apps-developers-guide/index.md

@@ -349,7 +349,7 @@ propagated to the payment app's service worker as a property of
 
 ```js
 const request = new PaymentRequest([{
-  supportedMethods: 'https://bobpay.xyz/pay',
+  supportedMethods: 'https://bobbucks.dev/pay',
   data: { transactionId: '****' }
 }], {
   displayItems: [{
@@ -532,11 +532,3 @@ To try it out:
 3. Press **Add a payment button**.
 4. Enter `https://paymenthandler-demo.glitch.me` to the **Payment Method Identifier** field.
 5. Press **Pay** button next to the field.
-
-## Next steps
-
-In this article, we learned how to handle optional information on the service
-worker. The final step for building a web-based payment app is to learn how to
-build the frontend.
-
-* Handling payments on the payment frontend (coming soon)

src/site/content/en/payments/handling-optional-payment-information/index.md

@@ -42,15 +42,15 @@ an array variable. Each element in the array comprises two components,
 
 For `supportedMethods`, the merchant needs to specify a [Payment Method
 Identifier](/setting-up-a-payment-method/#step-1-provide-the-payment-method-identifier)
-such as `https://bobpay.xyz/pay`. The existence and content of `data` depends on
+such as `https://bobbucks.dev/pay`. The existence and content of `data` depends on
 the content of `supportedMethods` and payment app provider's design.
 
 Both pieces of information should be provided by the payment app provider.
 
 ```javascript
 // Supported payment methods
 const paymentMethods = [{
-  supportedMethods: 'https://bobpay.xyz/pay',
+  supportedMethods: 'https://bobbucks.dev/pay',
   data: {
     ... // Optional parameters defined by the payment app provider.
   }
@@ -114,8 +114,8 @@ interface.
 To call the `show()` method, you must add a [user
 activation](https://developer.chrome.com/blog/user-activation/).
 This means the call must be inside an event listener, such as
-`click`. Note that Chrome currently bypasses this constraint, but plans to enforce
-it sometime in the future.
+`click`. Note that Chrome [enforces this constraint from version
+102](https://chromestatus.com/feature/5948593429020672).
 
 {% endAside %}
 

src/site/content/en/payments/how-payment-request-api-works/index.md

@@ -16,14 +16,6 @@ tags:
   - payments
 ---
 
-{% Aside 'warning' %}
-
-Shipping and address support in [the Payment Request API is removed from the
-specification](https://github.com/w3c/payment-request/pull/955) and is no longer
-functional.
-
-{% endAside %}
-
 Web Payments APIs are dedicated payment features built into the browser
 for the first time. With Web Payments, merchant integration with payment apps
 becomes simpler while the customer experience gets streamlined and more secure.
@@ -46,8 +38,10 @@ The process involves 6 steps:
 
     {% Img src="image/tcFciHGuF3MxnTr1y5ue01OGLBn2/IHztIcfJKeWDUIkugTkb.svg", alt="A diagram of the cheese shop website with BobPay app launched in a modal. The modal shows shipping options and total cost.", width="671", height="366" %}
 
-5. If the customer changes payment method, the merchant updates the transaction
-   details reflecting the change.
+5. If the customer changes any details (such as shipping options or their
+   address), the merchant updates the transaction details reflecting the change.
+
+    {% Img src="image/tcFciHGuF3MxnTr1y5ue01OGLBn2/BR9Od63aOdG9CaaD1z7K.svg", alt="A diagram showing the customer choosing a different shipping option in BobPay app modal. A second diagram showing the merchant updating the total cost displayed in BobPay.", width="777", height="702" %}
 
 6. After the customer confirms the purchase, the merchant validates the payment
    and completes the transaction.
@@ -63,6 +57,14 @@ object. This object includes important information about the transaction:
 
 * Acceptable payment methods and their data to process the transaction.
 * Details, such as the total price (required) and information about the items.
+* Options in which merchants can request shipping information such as a shipping
+  address and a shipping option.
+* Merchants can also request the billing address, the payer's name, email, and
+  phone number.
+* Merchants can also include optional [shipping
+  type](https://developers.google.com/web/fundamentals/payments/merchant-guide/deep-dive-into-payment-request#changing_the_shipping_type)
+  (`shipping`, `delivery`, or `pickup`) in the `PaymentRequest`. The payment app
+  can use that as a hint to display the correct labels in its UI.
 
 ```js
 const request = new PaymentRequest([{
@@ -79,6 +81,13 @@ const request = new PaymentRequest([{
     label: 'Total due',
     amount: { currency: 'USD', value : '22.15' }
   }
+}, {
+  requestShipping: true,
+  requestBillingAddress: true,
+  requestPayerEmail: true,
+  requestPayerPhone: true,
+  requestPayerName: true,
+  shippingType: 'delivery'
 });
 ```
 
@@ -194,18 +203,21 @@ passed to the `PaymentRequest` object in Step 1, which includes the following:
 
 * Payment method data
 * Total price
+* Payment options
 
 The payment app uses the transaction information to label its UI.
 
 ## Step 5: How a merchant can update the transaction details depending on customer's actions
 
 Customers have an option to change the transaction details such as payment
-method in the payment app. While the customer makes changes, the merchant
-receives the change events and updates the transaction details.
+method and shipping option in the payment app. While the customer makes changes,
+the merchant receives the change events and updates the transaction details.
 
 There are four types of events a merchant can receive:
 
 * Payment method change event
+* Shipping address change event
+* Shipping option change event
 * Merchant validation event
 
 ### Payment method change event
@@ -224,6 +236,61 @@ request.addEventListener('paymentmethodchange', e => {
 });
 ```
 
+### Shipping address change event
+
+A payment app can optionally provide the customer's shipping address. This is
+convenient for customers because they don't have to manually enter any details
+into a form and they can store their shipping address in their preferred payment
+apps, rather than on multiple different merchant websites.
+
+If a customer updates their shipping address in a payment app after the
+transaction has been initiated, a `'shippingaddresschange'` event will be sent
+to the merchant. This event helps the merchant determine the shipping cost based
+on the new address, update the total price, and return it to the payment app.
+
+```js
+request.addEventListener('shippingaddresschange', e => {
+  e.updateWith({
+    // Update the details
+  });
+});
+```
+
+If the merchant can't ship to the updated address, they can provide an error
+message by adding an error parameter to the transaction details returned to the
+payment app.
+
+{% Aside %}
+Merchants don't receive customers' full shipping address until they've
+authorized the payment.
+{% endAside %}
+
+### Shipping option change event
+
+A merchant can offer multiple shipping options to the customer and can delegate
+that choice to the payment app. The shipping options are displayed as a list of
+prices and service names the customer can select from. For example:
+
+* Standard shipping - Free
+* Express shipping - 5 USD
+
+When a customer updates the shipping option in a payment app, a
+`'shippingoptionchange'` event will be sent to the merchant. The merchant can
+then determine the shipping cost, update the total price, and return it to the
+payment app.
+
+```js
+request.addEventListener('shippingoptionchange', e => {
+  e.updateWith({
+    // Update the details
+  });
+});
+```
+
+The merchant can dynamically modify the shipping options based on the customer's
+shipping address as well. This is useful when a merchant wants to offer
+different sets of shipping options for domestic and international customers.
+
 ### Merchant validation event
 
 For additional security, a payment app can perform a merchant validation before
@@ -252,6 +319,9 @@ returns a promise that resolves to a
 The `PaymentResponse` object includes the following information:
 
 * Payment result details
+* Shipping address
+* Shipping option
+* Contact information
 
 At this point, the browser UI may still show a loading indicator meaning that
 the transaction is not completed yet.
@@ -278,7 +348,7 @@ they can either:
 ```js
 async function doPaymentRequest() {
   try {
-    const request = new PaymentRequest(methodData, details);
+    const request = new PaymentRequest(methodData, details, options);
     const response = await request.show();
     await validateResponse(response);
   } catch (err) {

src/site/content/en/payments/life-of-a-payment-transaction/index.md

@@ -136,9 +136,8 @@ to the service worker that handles payments.
 
 ## Next steps
 
-You learned how to register a service worker, set payment instruments for a
-web-based payment app. The next step is to learn how the service worker can
-orchestrate a payment transaction at runtime.
+The next step is to learn how the service worker can orchestrate a payment
+transaction at runtime.
 
 * [Orchestrating payment transactions with a service
   worker](/orchestrating-payment-transactions)

src/site/content/en/payments/registering-a-web-based-payment-app/index.md

@@ -69,7 +69,7 @@ is a URL-based string. For example, Google Pay's identifier is
 `https://google.com/pay`. Payment app developers can pick any URL as a payment
 method identifier as long as they have control over it and can serve arbitrary
 content. In this article, we'll use
-[`https://bobpay.xyz/pay`](https://bobpay.xyz/pay) as the payment method
+[`https://bobbucks.dev/pay`](https://bobbucks.dev/pay) as the payment method
 identifier.
 
 {% Aside %}
@@ -87,7 +87,7 @@ for the `supportedMethods` property. For example:
 
 ```js
 const request = new PaymentRequest([{
-  supportedMethods: 'https://bobpay.xyz/pay'
+  supportedMethods: 'https://bobbucks.dev/pay'
 }], {
   total: {
     label: 'total',
@@ -151,7 +151,7 @@ A payment method manifest file should look like this:
 
 ```json
 {
-  "default_applications": ["https://bobpay.xyz/manifest.json"],
+  "default_applications": ["https://bobbucks.dev/manifest.json"],
   "supported_origins": [
     "https://alicepay.friendsofalice.example"
   ]
@@ -178,19 +178,19 @@ Configure the payment method server to respond with a HTTP `Link` header with
 the `rel="payment-method-manifest"` attribute and the [payment method
 manifest](https://w3c.github.io/payment-method-manifest/) URL.
 
-For example, if the manifest is at `https://bobpay.xyz/payment-manifest.json`,
+For example, if the manifest is at `https://bobbucks.dev/payment-manifest.json`,
 the response header would include:
 
 ```http
-Link: <https://bobpay.xyz/payment-manifest.json>; rel="payment-method-manifest"
+Link: <https://bobbucks.dev/payment-manifest.json>; rel="payment-method-manifest"
 ```
 
 The URL can be a fully-qualified domain name or a relative path. Inspect
-`https://bobpay.xyz/pay/` for network traffic to see an example. You may use a
+`https://bobbucks.dev/pay/` for network traffic to see an example. You may use a
 `curl` command as well:
 
 ```shell
-curl --include https://bobpay.xyz/pay
+curl --include https://bobbucks.dev/pay
 ```
 
 {% Aside %}

src/site/content/en/payments/setting-up-a-payment-method/index.md

@@ -92,10 +92,9 @@ if used in a top-level document, with only a few exceptions:
 * `window.open()` is disabled.
 
 {% Aside 'caution' %}
-Payment Handler API is only supported in Chrome as of July 2020. However, since
-Chromium based browsers already have the implementation, some of them may expose
-the API in the future. Also, [Mozilla recently announced it's implementing the
-API](https://groups.google.com/g/mozilla.dev.platform/c/gBQp1URD1lE/m/Fswh-5-ZBgAJ).
+Payment Handler API is only supported in Chrome as of January 2023. However,
+since Chromium based browsers already have the implementation, some of them may
+expose the API in the future.
 {% endAside %}
 
 ### WebAuthn support