Skip to main content

​
In-app Purchases

In-app Purchases (IAP) in UptopiaKit let you define packages that your users can buy inside your app. UptopiaKit:
  • Provides a dashboard to configure IAP packages for each app/version.
  • Writes and keeps the package configuration on-chain / on contract on your behalf.
  • Exposes these packages to your app via the default IAP App Event.
  • Triggers a payment UI (currently using Base Pay) when the user initiates a purchase.
Your app remains in control of how these packages are presented and how they affect gameplay or features.

​
Defining IAP packages

For each application, developers can create multiple IAP packages in the UptopiaKit dashboard. Every package has:
  • Name — human-readable label shown in your app (e.g. “100 Gems”, “Premium Pass”).
  • Description — longer text describing what the user gets.
  • Package ID — a unique identifier you will reference from your app (e.g. gems_100, season_pass_s1).
  • Price — the price for the package (denominated according to the payment gateway / chain).
When you save or update an IAP package, UptopiaKit automatically writes the configuration to the underlying contract, so the source of truth for IAP pricing and metadata is always on-chain and consistent across clients.

​
How IAP works at runtime

At runtime, a typical IAP flow in your app looks like this:
  1. On app/game load, your app asks UptopiaKit for the list of available IAP packages for the current version using the default IAP App Event with type: "LIST".
  2. UptopiaKit returns a list of IAP packages (name, description, price, packageId, etc.) to your app.
  3. Your app renders a shop UI (or any in-game purchase entry points) based on that data.
  4. When the user chooses a package to buy, your app sends the default IAP App Event with type: "BUY" and the target packageId.
  5. UptopiaKit opens the payment UI (currently via Base Pay) and guides the user through payment.
  6. When the payment finishes (success/failure), UptopiaKit sends a result message back to your app so you can update state, grant entitlements, and show feedback.
All communication uses the App Events mechanism. For full payload/response shapes, see:
/kit/core-concepts/app-events

​
Integrating IAP in your app

IAP integration is built on the default IAP App Event. There are two main operations: LIST and BUY.

​
1. Fetch packages with IAP + LIST

On app or scene load, request the list of IAP packages defined for the current app/version: 
// Request available IAP packages
window.parent.postMessage({
  name: "IAP",
  data: {
    type: "LIST",
  },
});

// Listen for the response
window.addEventListener("message", (event) => {
  // TODO: validate event.origin in production
  const res = event.data;

  if (res?.type === "IAP_LIST") {
    const packages = res.payload;
    // packages: Array<{
    //   id: string;
    //   name: string;
    //   packageId: string;
    //   price: number;
    //   description: string;
    //   gameId: string;
    //   status: "active" | "inactive";
    // }>

    // Use this to render your in-game shop / purchase options.
  }
});
UptopiaKit ensures that the list corresponds to the current app version and environment.

​
2. Trigger a purchase with IAP + BUY

When a user clicks “Buy” in your UI, send a BUY request for the corresponding packageId: 
// Trigger a purchase for a specific package
window.parent.postMessage({
  name: "IAP",
  data: {
    type: "BUY",
    packageId: "your-package-id-here",
  },
});

// Listen for the result
window.addEventListener("message", (event) => {
  const res = event.data;

  if (res?.type === "IAP_RES") {
    // { status: 0 | 1, packageId?: string }
    const { status, packageId } = res.payload;

    if (status === 1) {
      // Payment success: grant the purchased item / currency
      // grantPurchaseToUser(packageId);
    } else {
      // Payment failed or cancelled: show error or do nothing
    }
  }
});
  • UptopiaKit will open a payment interface via Base Pay so the user can complete the transaction.
  • Your app should only grant items/benefits after receiving a successful result.
For more details on the IAP event contract (IAP_LIST, IAP_RES), see the IAP section in:
/kit/core-concepts/app-events

​
Responsibilities: UptopiaKit vs your app

UptopiaKit is responsible for:
  • Providing a dashboard to create and manage IAP packages.
  • Writing package configuration to contract based on what you configure.
  • Serving the current list of packages to your app via the IAP App Event.
  • Triggering and handling the payment UX with supported gateways (currently Base Pay).
  • Returning a clear payment result to your app.
Your app is responsible for:
  • Designing and rendering the shop / purchase UI (what to show, where, and how).
  • Interpreting IAP packages (how each package affects gameplay, items, or features).
  • Handling success/failure results from UptopiaKit and updating your local state accordingly.
  • Any additional anti-fraud, entitlement sync, or inventory management in your own systems.
In other words: UptopiaKit provides the packages, contract integration, and payments; your app owns the logic and experience.

​
Monitoring IAP history and income

UptopiaKit also provides a dashboard view so developers can track purchases and income over time for each app:
  • A History view inside the IAP section.
  • An Incomes view for approved, live versions.
These two views are intentionally separated by app/version state:
  • History (inside IAP):
    • Shows the purchase history for app versions that are still in development or otherwise not yet approved by UptopiaKit.
    • Useful for testing IAP flows, trying different prices, or running internal QA.
    • Lets you see test transactions and early-stage data without mixing them into production income.
  • Incomes:
    • Shows purchase history and income for app versions that have been reviewed and approved by the UptopiaKit team and are currently go-live.
    • Includes charts and summaries of income so you can track real revenue over time.
    • If your app does not yet have any approved/live version, this section will be unavailable (you will not be able to view Incomes until at least one version is approved and live).
This separation helps you clearly distinguish between:
  • Test / development purchases (visible in IAP → History).
  • Real production revenue (visible in Incomes for approved live versions).

​
Server-side validation (webhook, in development)

For apps with their own backend, you may want to validate purchases on the server and store purchase history in your own database. UptopiaKit is adding support for this flow:
  1. In your app’s Settings, you configure a webhook URL for IAP events.
  2. When a user completes (or fails) a payment, UptopiaKit will send a webhook request to your backend containing:
    • User identifier info (e.g. wallet, platform userId).
    • The packageId and other package metadata.
    • The transaction status and relevant payment details.
  3. Your backend can then:
    • Store the purchase in your own database.
    • Reconcile entitlements / inventory.
    • Combine webhook data with the in-app IAP_RES event to ensure consistency.
Important: This webhook-based server-side validation feature is under active development and not yet available in production. Until it is live, you should rely on the in-app IAP_RES event for granting purchases and can add your own additional checks where needed.