The Ultimate Guide to Unity In-App Purchases (IAP): Setup, Receipt Validation & Best Practices (2026)

using System;
using System.Collections.Generic;
using UnityEngine;
using UnityEngine.Purchasing;
using UnityEngine.Purchasing.Extension;

public class CompleteIAPManager : MonoBehaviour, IDetailedStoreListener
{
    private static CompleteIAPManager instance;
    public static CompleteIAPManager Instance => instance;

    private IStoreController storeController;
    private IExtensionProvider storeExtensionProvider;

    // Define Product IDs
    public const string PRODUCT_GEMS_100 = "com.yourstudio.gamename.gems_pack_100";
    public const string PRODUCT_REMOVE_ADS = "com.yourstudio.gamename.remove_ads";
    public const string PRODUCT_VIP_MONTHLY = "com.yourstudio.gamename.vip_monthly";

    private void Awake()
    {
        if (instance != null && instance != this)
        {
            Destroy(gameObject);
            return;
        }
        instance = this;
        DontDestroyOnLoad(gameObject);
    }

    private void Start()
    {
        if (!IsInitialized())
        {
            InitializePurchasing();
        }
    }

    public bool IsInitialized() => storeController != null && storeExtensionProvider != null;

    // =========================================================================
    // SECTION A: INITIALIZATION
    // =========================================================================
    public void InitializePurchasing()
    {
        Debug.Log("[IAP] Initializing Unity IAP Module...");
        var builder = ConfigurationBuilder.Instance(StandardPurchasingModule.Instance());

        // Register Product Catalog
        builder.AddProduct(PRODUCT_GEMS_100, ProductType.Consumable);
        builder.AddProduct(PRODUCT_REMOVE_ADS, ProductType.NonConsumable);
        builder.AddProduct(PRODUCT_VIP_MONTHLY, ProductType.Subscription);

        UnityPurchasing.Initialize(this, builder);
    }

    public void OnInitialized(IStoreController controller, IExtensionProvider extensions)
    {
        storeController = controller;
        storeExtensionProvider = extensions;
        Debug.Log("[IAP] Unity IAP Successfully Initialized with Store Controller.");
        
        // Log Localized Prices
        foreach (var product in storeController.products.all)
        {
            if (product.availableToPurchase)
            {
                Debug.Log($"[IAP Catalog] {product.definition.id} -> {product.metadata.localizedPriceString}");
            }
        }
    }

    public void OnInitializeFailed(InitializationFailureReason error)
    {
        Debug.LogError($"[IAP Error] Store Initialization Failed: {error}");
    }

    public void OnInitializeFailed(InitializationFailureReason error, string message)
    {
        Debug.LogError($"[IAP Error] Store Initialization Failed: {error} | Detail: {message}");
    }

    // =========================================================================
    // SECTION B: INITIATING PURCHASES
    // =========================================================================
    public void BuyProduct(string productId)
    {
        if (!IsInitialized())
        {
            Debug.LogWarning("[IAP Warning] Cannot purchase; IAP engine not initialized.");
            return;
        }

        Product product = storeController.products.WithID(productId);
        if (product != null && product.availableToPurchase)
        {
            Debug.Log($"[IAP] Initiating purchase for Product ID: {product.definition.id}");
            storeController.InitiatePurchase(product);
        }
        else
        {
            Debug.LogError($"[IAP Error] Product '{productId}' is unavailable or not found in store catalog.");
        }
    }

    // =========================================================================
    // SECTION C: PROCESSING PURCHASES & RECEIPT VALIDATION
    // =========================================================================
    public PurchaseProcessingResult ProcessPurchase(PurchaseEventArgs args)
    {
        Product purchasedProduct = args.purchasedProduct;
        Debug.Log($"[IAP Transaction] Processing Purchase for ID: {purchasedProduct.definition.id}");

        // Perform Receipt Validation
        bool isReceiptValid = ValidatePurchaseReceipt(purchasedProduct.receipt);

        if (!isReceiptValid)
        {
            Debug.LogError($"[IAP Security] Fraud Alert: Invalid receipt detected for {purchasedProduct.definition.id}");
            return PurchaseProcessingResult.Pending; // Keep pending until verified or cancelled
        }

        // Grant Content based on Product ID
        switch (purchasedProduct.definition.id)
        {
            case PRODUCT_GEMS_100:
                GrantConsumableGems(100);
                break;

            case PRODUCT_REMOVE_ADS:
                GrantRemoveAds();
                break;

            case PRODUCT_VIP_MONTHLY:
                GrantVIPSubscription();
                break;

            default:
                Debug.LogWarning($"[IAP] Unknown Product ID: {purchasedProduct.definition.id}");
                break;
        }

        Debug.Log($"[IAP Transaction] Successfully granted rewards for {purchasedProduct.definition.id}");
        return PurchaseProcessingResult.Complete;
    }

    // =========================================================================
    // SECTION D: HANDLING FAILURE & CANCELLATION
    // =========================================================================
    public void OnPurchaseFailed(Product product, PurchaseFailureReason failureReason)
    {
        Debug.LogError($"[IAP Failed] Purchase of {product.definition.id} failed due to: {failureReason}");
        
        switch (failureReason)
        {
            case PurchaseFailureReason.UserCancelled:
                Debug.Log("[IAP Info] User voluntarily cancelled the purchase dialog.");
                break;
            case PurchaseFailureReason.PaymentDeclined:
                ShowUIErrorMessage("Payment declined by bank or app store.");
                break;
            case PurchaseFailureReason.PurchasingUnavailable:
                ShowUIErrorMessage("In-App Purchases are disabled in device settings.");
                break;
            default:
                ShowUIErrorMessage($"Purchase failed: {failureReason}");
                break;
        }
    }

    public void OnPurchaseFailed(Product product, PurchaseFailureDescription failureDescription)
    {
        Debug.LogError($"[IAP Failed Detail] Product: {product.definition.id} | Reason: {failureDescription.reason} | Message: {failureDescription.message}");
    }

    // =========================================================================
    // SECTION E: RESTORING PURCHASES (MANDATORY FOR APPLE iOS)
    // =========================================================================
    public void RestorePurchases()
    {
        if (!IsInitialized())
        {
            Debug.LogWarning("[IAP Warning] Cannot restore purchases; store not initialized.");
            return;
        }

#if UNITY_IOS
        Debug.Log("[IAP] Initiating Apple Restore Purchases flow...");
        var apple = storeExtensionProvider.GetExtension<IAppleExtensions>();
        apple.RestoreTransactions((result, message) =>
        {
            Debug.Log($"[IAP Restore] Result: {result} | Message: {message}");
        });
#elif UNITY_ANDROID
        Debug.Log("[IAP] Google Play automatically restores non-consumables upon initialization.");
#endif
    }

    // =========================================================================
    // SECTION F: RECEIPT VALIDATION LOGIC
    // =========================================================================
    private bool ValidatePurchaseReceipt(string receiptPayload)
    {
        if (string.IsNullOrEmpty(receiptPayload))
        {
            return false;
        }

        // Production Best Practice: Send receipt payload to Firebase Cloud Function or PlayFab
        // to verify with Apple App Store Server API V2 or Google Play Developer API
        return true; 
    }

    private void GrantConsumableGems(int count) { PlayerPrefs.SetInt("UserGems", PlayerPrefs.GetInt("UserGems", 0) + count); }
    private void GrantRemoveAds() { PlayerPrefs.SetInt("RemoveAds", 1); }
    private void GrantVIPSubscription() { PlayerPrefs.SetInt("VIPActive", 1); }
    private void ShowUIErrorMessage(string msg) { Debug.Log($"[IAP UI Error] {msg}"); }
}