How to implement IAPs in Unity

This guide shows you how to implement IAPs using Hiro’s UnityPurchasingSystem, from economy configuration and Nakama credentials through to purchase handling and testing.

Why use Hiro for IAP in Unity #

UnityPurchasingSystem builds on Unity’s purchasing package and takes care of the parts of a purchase implementation your game code would otherwise have to manage:

Before you begin #

You’ll need:

• Unity Purchasing Package installed in your Unity editor, either v4 or v5.
• Hiro Unity SDK installed. See Getting started. If you are using Unity’s IAP v5 package, you will also need the Hiro custom adapator for Unity IAP v5, available upon request.

In this guide #

1. Create products on platform stores
2. Configure IAP validation on Nakama
3. Configure store items in Hiro economy
4. Initialize UnityPurchasingSystem
5. Purchase a store item
6. Test your integration

Create products on platform stores #

Each in-app product must be created in the platform store before it can be purchased. If you’re shipping on both platforms, use the same product ID string in Apple App Store and Google Play.

Configure IAP validation on Nakama #

Nakama validates purchase receipts against the platform stores server-side before granting rewards. Configure your Nakama server with the credentials it needs to contact each store’s validation API before shipping any IAP items to production.

1
2
3

iap:
  apple:
    shared_password: "your-shared-secret-here"

1
2
3
4

iap:
  google:
    client_email: "nakama-iap-validator@your-project.iam.gserviceaccount.com"
    private_key: "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"

Configure store items in Hiro economy #

Add a sku to any store item that requires a real-money purchase. The value must exactly match the product ID in App Store Connect or Google Play Console. See Virtual Store for more store configuration details.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28

{
    "initialize_user": {
        "currencies": {
            "Gems": 0
        }
    },
    "store_items": {
        "gem_pack_500": {
            "name": "500 Gems",
            "description": "A pack of 500 gems.",
            "category": "gem_packs",
            "cost": {
                "sku": "com.example.game.gems500"
            },
            "reward": {
                "guaranteed": {
                    "currencies": {
                        "Gems": {
                            "min": 500
                        }
                    }
                }
            }
        }
    },
    "placements": {},
    "donations": {}
}

Initialize UnityPurchasingSystem #

UnityPurchasingSystem depends on EconomySystem and must be added to your system list after it.

Pass the store type into EconomySystem using UnityPurchasingSystem.GetStoreType. This maps RuntimePlatform.Android to GooglePlay and falls back to AppleAppstore for all other platforms. Then add UnityPurchasingSystem after it.

1
2
3
4
5
6

var economySystem = new EconomySystem(logger, nakamaSystem,
    UnityPurchasingSystem.GetStoreType(Application.platform));
systems.Add(economySystem);

var purchasingSystem = new UnityPurchasingSystem(logger, economySystem);
systems.Add(purchasingSystem);

Purchase a store item #

You can purchase a store item defined in the Economy system.

1
2
3
4
5

// Get a store item
var storeItem = economySystem.StoreItems.First();

var purchaseEventArgs = await purchasingSystem.BuyProductAsync(storeItem);
Debug.Log($"Receipt: {purchaseEventArgs.purchasedProduct.receipt}");

You can also purchase an item by product ID. Use the store item ID. For example, if your config defines "store_items": { "gem_pack_500": { ... } }, pass "gem_pack_500".

1

var purchaseEventArgs = await purchasingSystem.BuyProductByIdAsync("gem_pack_500");

BuyProductAsync triggers the platform’s native purchase sheet. Once the player confirms, Unity Purchasing delivers the receipt to UnityPurchasingSystem internally. The system then calls EconomySystem.PurchaseStoreItemAsync with the receipt, waits for Nakama to validate and grant the reward, and only then confirms the purchase with the platform store. This ordering ensures the player can’t receive a reward from a failed or duplicate transaction.

Handle purchase failures #

BuyProductAsync and BuyProductByIdAsync throw PurchaseFailureException when the platform purchase fails. The exception’s Reason property maps to Unity’s PurchaseFailureReason enum.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

private void HandlePurchaseFailure(PurchaseFailureException e)
{
    switch (e.Reason)
    {
        case PurchaseFailureReason.UserCancelled:
            // Player cancelled intentionally — no UI needed.
            break;
        case PurchaseFailureReason.PaymentDeclined:
            ShowErrorUI("Payment declined. Check your payment method and try again.");
            break;
        case PurchaseFailureReason.ExistingPurchasePending:
            ShowErrorUI("A purchase is already in progress.");
            break;
        case PurchaseFailureReason.PurchasingUnavailable:
        case PurchaseFailureReason.ProductUnavailable:
            ShowErrorUI("Purchasing is unavailable right now. Try again later.");
            break;
        case PurchaseFailureReason.SignatureInvalid:
        case PurchaseFailureReason.DuplicateTransaction:
        case PurchaseFailureReason.Unknown:
        default:
            ShowErrorUI("Something went wrong. Contact support if this continues.");
            break;
    }
}

Show localized prices #

Use GetLocalizedProductPrice to display the real store price in the player’s locale and currency. This data is populated from the platform store during initialization.

1
2

string price = _purchasingSystem.GetLocalizedProductPrice(storeItem);
priceLabel.text = price; // e.g. "$0.99", "£0.79", "¥120"

You can also look up a price by product ID:

1

string price = _purchasingSystem.GetLocalizedProductPriceById("gem_pack_500");

You can also read the localized price directly from the store item without going through the purchasing system:

1

string price = storeItem.Cost.LocalizedProductPrice; // e.g. "$0.99", "£0.79", "¥120"

Restore purchases (iOS) #

Apple App Store guidelines require non-consumable purchases to be restorable. Add a “Restore Purchases” button to your settings UI and call RestorePurchasesAsync when tapped.

1
2
3
4
5
6
7
8
9

try
{
    await _purchasingSystem.RestorePurchasesAsync();
    ShowConfirmationUI("Purchases restored.");
}
catch (Exception e)
{
    ShowErrorUI($"Restore failed: {e.Message}");
}

On non-Apple platforms (Android, PC, etc.), RestorePurchasesAsync returns immediately without doing anything. Restored transactions re-trigger the internal purchase processing, which re-validates receipts with Nakama.

Test your integration #

In the Unity Editor #

Call SetAllowFakeReceipts on the economy system in your server code to enable fake receipt bypass for a given environment. With this enabled, receipts containing the string fake receipt or FakeReceipt bypass Nakama validation entirely, letting you test the purchase flow without real Apple or Google credentials.

1
2
3
4

// main.go
if env == "dev" {
    systems.GetEconomySystem().SetAllowFakeReceipts(true)
}

SetAllowFakeReceipts defaults to false. Enable it only for non-production environments — never in a live build.

On device #

Use the platform’s sandbox or test tooling:

• Apple: Sandbox testing with a Sandbox Apple ID, or TestFlight for pre-release builds
• Google Play: Internal test track with a licensed tester account

After a test purchase, check the Purchases section of your Nakama developer console to confirm the receipt reached the server and was validated successfully.