You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
The Payment Request API handles the actual payment transaction when a purchase is made by a user. The Payment Request API uses the item details that the Digital Goods API provides, to make the in-app purchase by using whichever billing payment method the user has set up at the Microsoft Store.
34
34
35
-
See [Payment Request API](https://developer.mozilla.org/docs/Web/API/Payment_Request_API) at MDN.
35
+
See:
36
+
*[Payment Request API](https://developer.mozilla.org/docs/Web/API/Payment_Request_API) at MDN.
The Digital Goods API is currently available for testing in Microsoft Edge. To test the API, use either of the following ways:
43
+
* To test your code locally: [Use a supported preview channel of Microsoft Edge on your dev machine](#use-a-supported-preview-channel-of-microsoft-edge-on-your-dev-machine).
44
+
* To test your code in your Microsoft Store PWA: [Register for the origin trial, then use your token at your website](#register-for-the-origin-trial-then-use-your-token-at-your-website).
45
+
46
+
Details are below.
47
+
48
+
49
+
<!-- ------------------------------ -->
50
+
#### Use a supported preview channel of Microsoft Edge on your dev machine
51
+
52
+
To test the Digital Goods API locally, before deploying your app to production, run Edge Dev or Edge Canary. These preview versions of Edge have the API enabled, as part of a running experiment.
53
+
54
+
To download a preview (insider) channel of Microsoft Edge, see [Become a Microsoft Edge Insider](https://aka.ms/microsoftedge).
55
+
56
+
57
+
<!-- ------------------------------ -->
58
+
#### Register for the origin trial, then use your token at your website
59
+
60
+
To test the Digital Goods API in production, with your users, use an origin trial token. With this approach, when your users download your PWA from the Microsoft Store, they will have the API enabled.
61
+
62
+
See:
63
+
*[Use origin trials in Microsoft Edge](../../origin-trials/index.md)
64
+
*[Digital Goods API](https://developer.microsoft.com/microsoft-edge/origin-trials/trials/4b4a9ead-d912-4349-87b3-25e5e50b4f13) at _Origin Trials_.
## Checking whether the Digital Goods API is available
40
69
41
-
To detect whether you've correctly enabled the API on your website, check for the `getDigitalGoodsService` method in the window object:
70
+
To detect whether you've correctly enabled the API on your website by using your origin trial token, check whether the `getDigitalGoodsService` method exists on the `window` object:
42
71
43
72
```javascript
44
73
if ('getDigitalGoodsService'inwindow) {
45
-
// Digital Goods API is supported!
74
+
//The Digital Goods API is supported.
46
75
} else {
47
76
console.log('DigitalGoodsService is not available.');
48
-
// Use other payment method
77
+
// Use another payment method.
49
78
}
50
79
```
51
80
81
+
See also:
82
+
*[getDigitalGoodsService() method](https://wicg.github.io/digital-goods/#getdigitalgoodsservice-method) of the `Window` interface.
## Connecting to the Microsoft Store Billing service (`getDigitalGoodsService` method)
86
+
## Connecting to the Microsoft Store Billing service (`window.getDigitalGoodsService` method)
55
87
56
-
Use the `getDigitalGoodsService` method to connect to the Microsoft Store Billing service.
88
+
Use the `getDigitalGoodsService` method of the `window` object to connect to the Microsoft Store Billing service. A [DigitalGoodsService interface](https://wicg.github.io/digital-goods/#digitalgoodsservice) is returned.
57
89
58
90
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 retrieve an instance of the service for Microsoft Store Billing, pass the string `"https://store.microsoft.com/billing"` as the payment method to the `getDigitalGoodsService` method.
59
91
60
92
If the method throws an error, the Microsoft Store Billing payment method is not available (such as when the user is accessing your PWA through the browser). Alternatively, consider providing a different payment method for transactions.
61
93
62
94
```javascript
63
95
if (window.getDigitalGoodsService===undefined) {
64
-
// Digital Goods API is not supported in this context.
96
+
//The Digital Goods API isn't supported in this context.
//Our preferred service provider is not available.
104
+
//The preferred service provider is not available.
73
105
// Use a web-based payment flow instead.
74
106
return;
75
107
}
76
108
```
77
109
110
+
This payment method `getDigitalGoodsService("https://store.microsoft.com/billing")` is available only for a PWA that's installed from the Microsoft Store, on Windows. No other settings are needed.
111
+
112
+
See also:
113
+
*[getDigitalGoodsService() method](https://wicg.github.io/digital-goods/#getdigitalgoodsservice-method) of the `Window` interface.
Use the `getDetails` method to query item details.
120
+
Use the `getDetails` method of the `DigitalGoodsService` interface to query item details.
83
121
84
122
After connecting the Digital Goods service to Microsoft Store, you can use the API to access product and purchase information. The `getDetails` method lets you get information about the items you’ve set up in the Partner Center. Display information such as the product title, description, and price in your app UI, so the user knows what's available for purchase.
85
123
@@ -105,20 +143,31 @@ The item ID is a string that represents the primary key of the items. In the Mi
105
143
106
144
The item's `price` is a `PaymentCurrencyAmount` that contains the current price of the item in the user's current region and currency. The `price` is designed to be formatted for the user's current locale by using `Intl.NumberFormat`, as shown above.
Use the `show` method to purchase an item, after you construct a request that contains the item details.
118
162
119
-
Once your products and details are displayed to the user, you can implement the purchase flow by using the Payment Request API. When combined with the Digital Goods API, the only required input parameter is `methodData`.
## Purchasing an item (`PaymentRequest` constructor and `show` method)
165
+
166
+
After your products and details are displayed to the user, implement the purchase flow by using the Payment Request API. To purchase an item, first construct a request that contains the item details by using the `PaymentRequest` constructor, and then use the `show` method of the `PaymentRequest` object to start the payment flow.
120
167
121
-
Use the `supportedMethods` member of the `methodData` parameter in the `PaymentRequest` to identify Microsoft Store Billing as the payment method with the string `"https://store.microsoft.com/billing"`. Then in the `data` member, pass along the item ID as the `sku`.
168
+
When combined with the Digital Goods API, the only required input parameter for the `PaymentRequest` constructor is `methodData`. In the constructor's parameter:
169
+
* In the `supportedMethods` member, specify Microsoft Store Billing as the payment method, as the string `'https://store.microsoft.com/billing'`.
170
+
* In the `data` member, pass along the `itemId` as the `sku`.
@@ -132,33 +181,30 @@ const request = new PaymentRequest([
132
181
]);
133
182
```
134
183
135
-
Then call the `show` method to start the payment flow:
184
+
Then call the `show` method of the `PaymentRequest` object, to start the payment flow:
136
185
137
186
```javascript
138
187
constresponse=awaitrequest.show();
139
188
```
140
189
141
-
This will display the Store purchase UI to the user, where the user can view details about the product that they're trying to purchase. During this process, the current browser session is temporarily disabled until the purchase flow is complete. The user can either cancel the transaction, or proceed with the payment:
190
+
This displays the Store purchase UI to the user, where the user can view details about the product that they're trying to purchase. During this process, the current browser session is temporarily disabled until the purchase flow is complete. The user can either cancel the transaction, or proceed with the payment:
142
191
143
192
* If the user cancels the payment, the Promise that's returned by the `show` method will be rejected with an error.
144
193
145
-
* If the user successfully pays and completes the purchase, the Promise will resolve with a `PaymentResponse`.
194
+
* If the user successfully pays and completes the purchase, the Promise will resolve with a `PaymentResponse`. In the `details` property of the payment response, a purchase token is returned.
146
195
147
-
In the `details` property of the payment response, a purchase token is returned.
The payment response returns a _purchase token_ string, which can be used for direct communication between your server and the service provider beyond the Digital Goods API. Such communication can allow you to independently verify information about the purchase before granting entitlements.
154
-
155
-
Some stores might require that you (the developer) acknowledge a purchase after the purchase has succeeded, to confirm that the purchase has been recorded.
Use the `consume` method of the `DigitalGoodsService` interface to consume a purchase.
162
208
163
209
A _consumable purchase_ is a purchase that's designed to be purchased multiple times. A consumable purchase usually needs to be marked as "consumed" before the purchase can be purchased again by the user. An example of a consumable purchase is an in-game powerup that makes the player stronger for a short period of time.
164
210
@@ -168,11 +214,14 @@ To mark a purchase as "consumed", use the `consume` method:
168
214
digitalGoodsService.consume(purchaseToken);
169
215
```
170
216
217
+
See also:
218
+
*[consume() method](https://wicg.github.io/digital-goods/#consume-method) of the `DigitalGoodsService` interface.
Use the `listPurchases` method to check existing purchases. This method returns information about the user's existing purchases. This method allows a client to get a list of items that are currently owned or purchased by the user. This may be necessary, to do either of the following:
224
+
Use the `listPurchases` method of the `DigitalGoodsService` interface to check existing purchases. This method returns information about the user's existing purchases. This method allows a client to get a list of items that are currently owned or purchased by the user. This may be necessary, to do either of the following:
176
225
177
226
* Check for entitlements, such as whether a subscription, promotional code, or permanent upgrade is active.
178
227
@@ -191,11 +240,16 @@ for (const purchase of purchaseList) {
191
240
192
241
The `listPurchases` method doesn't return consumed products or expired subscriptions.
193
242
243
+
See also:
244
+
*[listPurchases() method](https://wicg.github.io/digital-goods/#listPurchases-method) of the `DigitalGoodsService` interface.
## Getting the purchase history (`listPurchaseHistory` method)
197
249
198
-
Use the `listPurchaseHistory` method to get the purchase history. This method returns a list that shows the most recent purchase made by the user for each item, regardless of whether the purchase is expired, canceled, or consumed. This method returns a list of `PurchaseDetails` containing the `itemId` and `purchaseToken` for each purchase.
250
+
Use the `listPurchaseHistory` method of the `DigitalGoodsService` interface to get the purchase history.
251
+
252
+
This method returns a list of `PurchaseDetails` containing the `itemId` and `purchaseToken` for each purchase. The list includes the most recent purchase made by the user for each item, regardless of whether the purchase is expired, canceled, or consumed.
0 commit comments