Verify Xbox in-app purchases
Verify Xbox in-app purchases in a Cloud Code module before granting entitlements.
読み終わるまでの所要時間 4 分最終更新 3ヶ月前
Use Cloud Code modules to validate Xbox purchases on the server before you grant entitlements. This prevents spoofed or tampered clients from granting items without confirmed ownership with the Microsoft Store Collections API (Microsoft) on the server side.
The instructions on this page use the NuGet package, which wraps Microsoft Store Collections API calls and handles Microsoft Entra ID (formerly Azure AD) service authentication.
Com.Unity.Services.CloudCode.IAPVerification process overview
The verification process described on this page works as follows:
- The game client completes a purchase in the Xbox Store.
- The game client obtains a Collections ID (business-to-business) token from the Microsoft GDK.
- The game client calls a Cloud Code function, and passes the token and product IDs for verification.
- The Cloud Code module uses your service credentials to authenticate with Entra ID.
- The module calls the Microsoft Store Collections API, which returns which products the player owns.
- The module grants entitlements only for products that Microsoft confirms as owned.
The Collections ID token is a client-to-server handoff token. The player's Microsoft account credentials never reach the module. The module caches Entra ID access tokens in memory for the lifetime of the worker, minus a five-minute refresh buffer. This buffer means most requests skip the token fetch entirely.
Prerequisites
Before you begin, make sure you meet the following requirements:
- A Cloud Code module project that targets .NET 9.
- An Entra ID app registration linked to your Partner Center account with access to the Microsoft Store Collections API and the scope. Refer to Register an application in Microsoft Entra ID (Microsoft) for full setup instructions.
https://onestore.microsoft.com/.default - Cloud Code secrets configured for Entra ID credentials.
Use the following secret keys:
Secret key | Description |
|---|---|
| Entra ID directory (tenant) ID. |
| Entra ID application (client) ID. |
| Entra ID application client secret. |
Install the package
注
NuGet hosts the package publicly. You don't need a private feed or authentication.
Com.Unity.Services.CloudCode.IAPTo install the Xbox verification package to your Cloud Code module, run the following command from your Cloud Code module project using .NET CLI:
dotnet add package Com.Unity.Services.CloudCode.IAP
Register the Xbox verification client
To register the Xbox verification client in your module setup:
-
Add the verification client in yourimplementation:
ICloudCodeSetupusing Unity.Services.CloudCode.Apis.Extensions;using Unity.Services.CloudCode.Core;using Unity.Services.CloudCode.IAP.Extensions;public class ModuleConfig : ICloudCodeSetup{ public void Setup(ICloudCodeConfig config) { config.AddGameApiClient() .AddIapXboxVerificationClient(); }} -
If your secrets use different key names, pass a configuration callback:config.AddIapXboxVerificationClient(options =>{ options.TenantIdKey = "MY_TENANT_ID"; options.ClientIdKey = "MY_CLIENT_ID"; options.ClientSecretKey = "MY_CLIENT_SECRET";});
Get the Collections ID token on the game client
The Collections ID is the business-to-business token the game client obtains from the Microsoft GDK. The API to get this ID requires a provided by . Add the following Cloud Code function to your module so the game client can call it to get the token:
serviceTicketGetAccessTokenusing System.Threading.Tasks;using Unity.Services.CloudCode.Core;using Unity.Services.IAP.Api;using Unity.Services.IAP.Model;public class XboxPurchaseVerifier{ [CloudCodeFunction("GetAccessToken")] public async Task<string> GetAccessToken( IExecutionContext context, IXboxTokenProvider xboxTokenProvider, ISecretClient secretClient) { var tokenResponse = await xboxTokenProvider.GetAccessTokenAsync( context, secretClient); return tokenResponse; }}
Next, call (Microsoft) with this token as the parameter to get the Collections ID. For Collections ID details, refer to To create a User Collections ID key for the Microsoft Store Collections service (Microsoft).
XStoreGetUserCollectionsIdAsyncserviceTicketValidate purchase ownership
To validate purchase ownership in a Cloud Code function before you grant entitlements:
- Inject into your function.
IXboxVerificationApi - Call to verify a purchase before granting entitlements. The method returns which products the player owns and which are missing.
ValidateOwnershipAsync
using System.Collections.Generic;using System.Threading.Tasks;using Unity.Services.CloudCode.Core;using Unity.Services.IAP.Api;using Unity.Services.IAP.Model;public class XboxPurchaseVerifier{ [CloudCodeFunction("ValidateXboxPurchases")] public async Task<XboxOwnershipValidationResult> ValidateXboxPurchases( IExecutionContext context, IXboxVerificationApi xboxVerificationApi, string collectionsIdToken, List<string> productIds, string? sandboxId = null) { return await xboxVerificationApi.ValidateOwnershipAsync( context, collectionsIdToken, productIds, sandboxId); }}
The parameter is optional and typically omitted for retail purchases.
sandboxIdThe validation result contains the following fields:
Field | Type | Description |
|---|---|---|
| | Returns true when the player owns every requested product. |
| | Owned products, including status, acquisition date, and other metadata. |
| | Requested product IDs not found in the player's collection. |
Query entitlements for a single product
Use when you need the raw Collections API response for a single product, including SKU details:
QueryEntitlementsAsyncvar response = await xboxVerificationApi.QueryEntitlementsAsync( context, collectionsIdToken, productId: "9NBLGGH4NNS1", skuId: "0010", // Optional sandboxId: null); // Null means retailforeach (var item in response.Items){ Console.WriteLine($"{item.ProductId} - {item.Status} (acquired {item.AcquiredDate})");}
Verify the module
To verify the module after deployment:
- Trigger from your game client or from Cloud Code in the Unity Dashboard.
ValidateXboxPurchases - Confirm that the function response sets for products the player owns.
AllOwned: true - Confirm that unknown product IDs appear in .
MissingProductIds - Check module logs in the Unity Dashboard for successful Microsoft Store collection API calls.
Authentication failures appear as Entra ID errors. Invalid or expired values appear as responses from Microsoft Store Collections API. After you verify the module works correctly, you can use it in your game client's purchase flow to protect against spoofed or tampered purchases.
collectionsIdToken401 Unauthorized