Implement Play Billing in your PWA

Digital Goods API

The Digital Goods API⁠ is an interface between your app and Google Play. It allows you to retrieve the digital products and details you’ve entered for your in-app products and subscriptions in the Play Console as well as retrieve existing purchases a user has made. If you haven’t added in-app products or subscriptions in the Play Console yet, make sure to follow the Play Console setup for Play Billing.

On November 30th, 2021, ChromeOS 96 was released with the Digital Goods API 2.0 implementation.

The origin trial for the first version of the Digital Goods API ended on January 30, 2022. Therefore it is now deprecated and only v2 of the API is available.

In May 2022, Google Play Console introduced changes to their subscription models⁠ which are not currently supported by the Digital Goods API.The previous subscription model is still supported by Play. You’ll notice that in the Play Console existing subscription SKUs have automatically been converted to this new format while keeping it backwards compatible. Any new subscription SKUs you create will need to also be marked as backwards compatible in the Play Console⁠ for it to be compatible with the Digital Goods API.

On May 22, 2022, The Digital Goods v2 origin trial ended and the API has been shipped as stable on ChromeOS 100. Therefore, the Digital Goods API stopped working for users who are not on ChromeOS 100 or later. Make sure you’ve implemented feature detection to handle this scenario and disable any features that require the Digital Goods API. You can let users know that they can update their ChromeOS version to enable those features again.

On June 23rd, 2022, ChromeOS 103 was released with the Digital Goods API 2.1 implementation. This release does not have any breaking changes and only includes new methods and additional fields: listPurchaseHistory() and itemType.

Starting on August 2, 2023, Google Play requires all new apps to use version 5 or newer of the Play Billing LIbrary. By November 1, 2023, updates to existing apps must also use version 5 or newer of the Play Billing Library. Therefore, an existing app will continue to work but to publish a new version of an existing app, use the Bubblewrap version 1.20.1⁠ or newer to continue to be compliant with Google Play requirements.

Payment Request API

The Payment Request API⁠ handles the actual payment transaction when a purchase is made. It utilizes the item details that the Digital Goods API provides to make the in-app purchase using the appropriate payment method, which in our case is Google Play Billing.

Feature detect the Digital Goods API

You can detect if the Digital Goods API is supported by checking for the getDigitalGoodsService method in the window object.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
} else {
  console.log('DigitalGoodsService is not available.');
  // Use another payment method
}

Connect to the Google Play Billing service

The Digital Goods API was designed to be compatible with various browsers and digital stores, similar to how the Payment Request API is browser-agnostic and can be used with different payment providers. To obtain an instance of the service associated with Google Play Billing, pass the string "https://play.google.com/billing" as the payment method to getDigitalGoodsService().

If the method throws an error, the Google Play Billing payment method is not available (e.g. the user is accessing your PWA through the browser). Instead, you should offer another payment method for transactions.

if ('getDigitalGoodsService' in window) {
  // Digital Goods API is supported!
  try {
    const service = await window.getDigitalGoodsService('https://play.google.com/billing');
    // Google Play Billing service is available
  } catch (error) {
    // Google Play Billing service is not available. Use another payment flow.
  }
}

Get item details

Once you have the Digital Goods service connected to Google Play, you can use the API to retrieve information about products and purchases.

The getDetails() method lets you get information about the items you’ve set up in the Play Console. Information like the product title, description, and price should be displayed to the user in your app UI so they know what is available for purchase and for how much.

The getDetails() method will need a list of item IDs which correspond to the product IDs of the in-app products and subscriptions you created in the Play Console.

const itemDetails = await service.getDetails(['product_1', 'product_2', 'product_3']);
for (const item of itemDetails) {
  // Display item information to user
  displayItem(item.title, item.description, item.price);
}

To get the appropriate price for the user’s locale, you will need to do some additional formatting:

const localePrice = new Intl.NumberFormat(navigator.language, {
  style: 'currency',
  currency: item.price.currency,
}).format(item.price.value);

In v2.1 of the API, one of the fields returned by getDetails() is itemType. It is an enum where the value is ”product” or ”subscription” to denote whether the corresponding item is an in-app product or subscription, respectively. Being able to differentiate between the two types of products can be useful if you need to apply different treatments to each product type. For example, you may have a specific page for users to subscribe and another page for the other non-subscription products. It’s also useful for knowing the appropriate Google Play Developer API REST resource to use in your backend (purchases.products or purchases.subscriptions).

Purchase an item

Once your products and details are displayed to the user, you can build the purchase flow with the Payment Request API. When used in conjunction with the Digital Goods API, only one input parameter is required: methodData.

Play Billing only allows the purchase of a single item at a time; the price and details of the item are already known by the Play server, so the details⁠ parameter is not necessary. See the explainer⁠ for a more detailed explanation.

Use the supportedMethods member of the methodData⁠ parameter in the PaymentRequest to identify Google Play Billing as the payment method with the string "https://play.google.com/billing". Then in the data member, pass along the item ID as the sku.

const paymentMethodData = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
    },
  },
];

Then create the payment request and call show() to start the payment flow:

const request = new PaymentRequest(paymentMethodData);
const paymentResponse = await request.show();

This will display the Play purchase UI to the user, where they’ll see the details about the product they’re trying to purchase. They can either abandon the transaction or proceed with the payment. If the user cancels the payment, the promise returned by show() will be rejected with an error. If they successfully pay and complete the purchase, the promise will resolve with a PaymentResponse. In the details property of the payment response, a purchase token is returned.

To prevent fraud, it’s critical to verify the purchase and purchase token on your back-end server. It’s also a good idea to keep track of users and their associated purchase tokens. Learn how to implement the verification on your back-end server.

After validating the purchase, call complete() on the payment response to finish the payment flow and close out the billing UI. You can also pass in an optional result string to indicate the state of the payment process. It is up to the browser whether to provide any indication of this result to the user. Chrome does not create any user-visible cues so it is recommended that you display your own error or success messages in your PWA.

/*
Changes were recently made so that the PaymentResponse `details`
property returns the purchase token as `purchaseToken`
instead of `token`.

Note that `token` will be deprecated at some point in the future.
To ensure that your app won't be affected by this, make the
change to `purchaseToken` in your client code and use the latest
version of Bubblewrap (v1.13.5 and later) to update and generate
a new app package to upload to the Play Console.
*/
const { purchaseToken } = paymentResponse.details;

let paymentComplete;
if (validatePurchaseOnBackend(purchaseToken)) {
  paymentComplete = await paymentResponse.complete('success');
  // Let user know their purchase transaction has successfully completed and been verified
} else {
  paymentComplete = await paymentResponse.complete('fail');
  // Let user know their purchase transaction failed to verify
}

const paymentMethod = [
  {
    supportedMethods: 'https://play.google.com/billing',
    data: {
      sku: item.itemId,
      oldSku: oldPurchase.itemId,
      purchaseToken: oldPurchase.purchaseToken,
      prorationMode: 'immediateAndChargeProratedPrice',
    },
  },
];

Acknowledge a purchase

After a user purchases an item, you should grant them the proper entitlements (access to the item or content they’ve just purchased). Then, acknowledge the purchase. Acknowledging a purchase lets Google Play know that you’ve received and processed the purchase appropriately.

You should acknowledge purchases from your backend server using the Google Play Developer API. We recommend granting entitlements and then acknowledging the purchase together in your backend server.

1. After a user makes a purchase client-side, send the purchase token and item ID in a request to your backend server.
2. On your backend, to get details about the purchase to verify it, call:
   • purchases.products.get⁠ for in-app items.
   • purchases.subscriptions.get⁠ for subscriptions.
3. Grant the appropriate entitlement in your backend database.
4. Then acknowledge the purchase by calling:
   • purchases.products.acknowledge⁠ for in-app items.
   • purchases.subscriptions.acknowledge⁠ for subscriptions.

// After the user purchases the item, send the purchase token and item ID to your backend to grant the entitlement and acknowledge it right away

. . .
// When the user uses the item or if it is a repeatable item, consume it so it’s available for purchase again.
service.consume(purchaseToken);
}

Check existing purchases

The last key user flow is to check for existing purchases (in-app products that haven’t been consumed yet and on-going subscriptions) to let your users know what subscription or items they currently own. These existing purchases will be from previous Google Play purchases on any device made in-app or on the Play Store. Purchases made from outside the app in the Play Store are called out-of-app purchases.

When retrieving existing purchases, you should also check the acknowledgement status and acknowledge any purchases that were previously made but did not properly get acknowledged. It is recommended that purchases get acknowledged as soon as possible so the user’s entitlements are up-to-date and properly reflected in the app.

The Digital Goods API listPurchases() method will return a list of PurchaseDetails that contains the itemId and purchaseToken for each of the purchases. You will need to use the Google Play Developer API on your backend server to check the state of purchases and acknowledge them appropriately. You should:

1. Call the Digital Goods API listPurchases() method client-side to retrieve the user’s list of purchases.

2. For each purchase, pass the purchaseToken and itemId to your backend.

3. If appropriate, grant entitlement in your backend database.

4. Then call:

   • purchases.products.get⁠ for in-app items.
   • purchases.subscriptions.get⁠ for subscriptions.

   and check the acknowledgementState.

5. If the value is 0 (yet to be acknowledged), then call:

   • purchases.products.acknowledge⁠ for in-app items.
   • purchases.subscriptions.acknowledge⁠ for subscriptions.

Learn more about how to verify purchases on your back-end server before granting entitlements.

Out-of-app purchases

Out-of-app purchases are purchases not made in the normal in-app purchase flow. These will usually occur in the Play Store instead of in your app. There are two main ways users may make an out-of-app purchase:

• Redeeming a promo code: In the Play Store user menu, in “Offers & notifications” -> “Redeem promo code” or in “Payments & subscriptions” -> “Redeem gift code”.
• Resubscribing: In the Play Store user menu, in “Payments & subscriptions” -> “Subscriptions”. Here, users may manage all their subscriptions across different apps. For expired or canceled subscriptions, users have the option to “Resubscribe”.

When users resubscribe from the Play Store, their purchases are not acknowledged automatically which may result in them being refunded. This behavior is intentional because users should only be charged for their subscription if they open the app to use it. The user may see a “Confirm subscription” like so, reminding them to open the app.

It is up to you as the developer to implement acknowledgement of these once the user launches the app. That’s why we recommend checking for existing purchases (usually when the app first launches) and acknowledging any purchases that are not acknowledged yet.

Let users manage subscriptions

For a good user experience, it is important to provide a way for users to manage and cancel their subscriptions in-app. We recommend creating a deep link, on a settings page or menu, that will redirect the user to the Play Store’s subscription management page for your app. Replace the following URL with your appropriate “sub-product-id” and “app-package-name”:

https://play.google.com/store/account/subscriptions?sku=sub-product-id&package=app-package-name

Next steps

These user flows and code snippets are a basic implementation to demonstrate how to use the DIgital Goods API and Payment Request API in your PWA to implement Play Billing. You should utilize the APIs as it makes sense in your app’s context and use cases. For an example of an end-to-end implementation, check out our open-source sample⁠.

Then, take a look at how to implement crucial Play Billing components in your back-end server to keep your app secure and always updated with your user’s entitlements.