Highrise Payments API Integration Tutorial: 2026 Guide

TL;DR

The Highrise Payments API lets World creators sell items, features, and access for Gold directly inside their published Worlds. This tutorial covers every key term, API method, error code, Lua scripting pattern, and security practice you need to build your first in game purchase flow. Creators earn up to 90% of each sale as Earned Gold, which can be cashed out through the Creator Exchange once you hit 35,000 Earned Gold.

What This Guide Covers and Who It’s For

If you’re building a World in Highrise Studio and want players to spend Gold inside your experience, the Payments API is how you make that happen. It’s the Lua scripted service that connects your World to the Highrise economy, handling everything from prompting a player to buy something to depositing revenue in your account.

This highrise payments API integration tutorial is designed as a companion reference. It defines every concept you’ll encounter, walks through creating Lua scripts and payment handler modules, explains how to persist purchase data, and points you to the official docs for full code samples. Bookmark it alongside the API reference and come back whenever a term or error code trips you up.

Whether you’re a first time creator exploring Highrise Studio or an experienced builder adding monetization to an existing World, this page has you covered.

Download Highrise to start building and testing your Worlds today.

Core Concepts

Before writing a single line of Lua, you need to understand seven foundational terms. These show up everywhere in the documentation, the Creator Portal, and creator forums.

Payments API

The Payments API is the Lua service inside Highrise Studio that manages in game purchases. It splits responsibility between client and server: the client side opens purchase dialogs for players, while the server side handles fulfillment, validation, and acknowledgment. This separation exists for security reasons, and breaking it is the fastest way to introduce exploits into your World.

In World Purchases (IWP)

In World Purchases are the actual products players buy with Gold inside your World. Each IWP has a unique product ID that you define in the Creator Portal. Products can be items, feature unlocks, bundles, or access passes. Think of IWPs as your storefront inventory, configured through a web dashboard and triggered through Lua scripts.

For a deeper walkthrough of product setup, see the guide on setting up In World Purchases.

Gold

Gold is Highrise’s primary virtual currency. Players buy it or earn it, then spend it on avatar items, marketplace trades, and In World Purchases. When a player buys something in your World, they pay in Gold. For a full breakdown of the currency system, check out the Gold currency mechanics explainer.

Earned Gold

Earned Gold is the specific Gold credited to creators through IWP sales or engagement based payouts. It functions like regular Gold for spending, but it also qualifies for cash out. The distinction matters because only Earned Gold flows into the Creator Exchange. Learn more about how creators earn it.

Creator Exchange

The Creator Exchange is the dashboard where you track your Earned Gold balance and convert it into real money. According to the official Creator Exchange documentation, creators need a minimum of 35,000 Earned Gold to initiate a cash out. This is the finish line of the monetization pipeline: IWP sale, Earned Gold deposit, then Creator Exchange withdrawal.

World Wallet

A World Wallet is a per World Gold reserve that lets you programmatically reward players. You can fund it by depositing Gold from your own wallet or by routing IWP earnings directly into it. The Wallet API provides server side methods like Wallet.TransferGoldToPlayer and Wallet.GetWallet to manage these transfers in code.

The official docs carry a clear warning here: using World Wallet means sending real Gold to players, which can motivate malicious attempts to hack and exploit your World. For seasonal promotion strategies using the Wallet, see this World Wallet guide.

Creator Portal

The Creator Portal at create.highrise.game is your command center. You create and configure IWP products, manage World Wallet settings, track analytics, and monitor Earned Gold all from this web dashboard. Every highrise payments API integration tutorial starts here because you cannot sell anything without first setting up your products in the Portal.

Lua Only Scripting in Highrise

Highrise Studio uses Unity as its editor environment, but all gameplay logic (including payment flows) is written exclusively in Lua. You don’t write C# MonoBehaviours or attach traditional Unity scripts. Instead, you create .lua files and attach them to GameObjects through the Highrise Studio component system.

This is a point that trips up many newcomers, especially those with Unity experience. Practitioners on the Highrise Create Forum regularly ask whether they can use C# alongside Lua, and the answer is no. The platform compiles and runs Lua scripts through its own runtime. C# is only used under the hood by the Highrise engine itself.

Why Lua?

Lua is lightweight, easy to learn, and sandboxed. Highrise chose it specifically because World creators don’t need deep engine expertise to build functional experiences. If you’ve written scripts in Roblox (which also uses a Lua variant called Luau), the transition is straightforward. The syntax is nearly identical, though the APIs differ entirely.

For creators coming from zero scripting background, the Highrise Studio beginner glossary covers the fundamentals of working with Lua in this environment.

How Lua Scripts Attach to GameObjects

Every Lua script in Highrise Studio gets attached to a GameObject in the Unity scene hierarchy. You do this through the Inspector panel by adding a Highrise Script component and selecting your .lua file. The script then runs in the context of that GameObject, with access to self (the script instance) and the various Highrise APIs.

This attachment model matters for payment integration because you’ll typically have at least two scripts:

1. A client script attached to a UI element or interactive object (like a shop button or NPC) that triggers PromptPurchase
2. A server script that handles the PurchaseHandler callback, fulfills the purchase, and calls AcknowledgePurchase

These must be separate scripts running in separate contexts. Client scripts execute on the player’s device. Server scripts execute on Highrise’s servers. You cannot mix them, and attempting to call server methods from a client script (or vice versa) will throw errors.

Revenue Share Explained

This is where things get a bit confusing, and it’s worth addressing directly.

The 90/10 vs. 70/30 Discrepancy

The official Payments tutorial page states that creators earn 90% of each IWP sale as Earned Gold, with 10% covering platform and app store fees. However, a separate documentation page on accepting Gold payments states that creators earn 70%, with 30% going to platform fees, hosting, and development costs.

Both are official sources. The 90/10 figure appears on the more recent Payments tutorial and in the Help Center, which suggests it reflects the current IWP rate. The safest approach: check your Creator Portal for the actual rate applied to your account. Highrise may update these figures, so treat the Portal as your authoritative source.

For context, this compares favorably to other platforms. Roblox developers receive between 50% and 70% on paid access games depending on price tier.

Two Ways to Earn

Highrise creators earn through two distinct paths:

1. In World Purchases via the Payments API, where players spend Gold on your products
2. Engagement based payouts deposited daily, driven by how much time Highrise+ subscribers spend in your World

For engagement payouts, your World must maintain a 50%+ rating and engage at least one Highrise+ subscriber per day (other than yourself). A detailed breakdown of this system is available in the HR+ engagement payouts guide.

How the Money Flows

The path from player purchase to your bank account looks like this:

Player spends Gold → You earn Earned Gold (minus platform fee) → Earned Gold appears in Creator Exchange → You cash out once you hit 35,000 Earned Gold.

API Methods and Functions

Here’s every method in the Payments API, what it does, and where it runs. This is the reference table you’ll keep coming back to during your highrise payments API integration tutorial workflow.

Client Side Methods

PromptPurchase(productId, callback) opens the purchase dialog for a player. You call this when a player taps a buy button, interacts with an NPC shopkeeper, or triggers any purchase worthy event. The callback returns a result, but here’s the critical warning from the docs: do not rely on the PromptPurchase paid callback to determine if a purchase was successful. The paid result can be a false positive. Always validate on the server.

ClosePurchasePrompt() dismisses any open purchase dialog. Useful for timeout scenarios or UI cleanup.

Server Side Methods

PurchaseHandler is a property you assign a callback function to. It fires whenever a purchase completes. This is where you grant items, unlock features, and acknowledge the transaction. This is the most important piece of your payment integration.

AcknowledgePurchase(purchase, wasConsumed, callback?) confirms that you’ve fulfilled the purchase. Until you call this, the transaction remains unresolved. The wasConsumed parameter tells the system whether the purchased item was a one time consumable.

GetProduct(productId, callback) retrieves details for a single product. Useful for displaying current prices or checking product availability at runtime.

GetProducts(cursorId, callback) returns a paginated list of all your IWP products.

GetPurchases(player, productId, limit, cursorId, callback) pulls a player’s purchase history for a specific product. Use this to check whether a player already owns something before prompting them to buy it again.

All server side payment methods are only available on the SERVER. Client side methods are only available on the CLIENT. Mixing these up will cause errors.

PaymentsError Codes

When something goes wrong, the API returns a PaymentsError value. Here’s what each one means and what to do about it.

Error Code	What It Means	Common Cause	What to Do
None	Operation succeeded	N/A	Proceed normally
InternalError	Something broke server side	Platform issue	Retry after a delay, check platform status
InvalidProductId	The product ID doesn’t match any IWP	Typo in product ID or product not published	Verify the ID in Creator Portal
InvalidPurchaseId	The purchase ID is wrong	Corrupted or misreferenced purchase object	Log the purchase object and inspect
InvalidUserId	Bad user reference	Player disconnected or invalid reference	Validate the player object before calling
PurchaseAlreadyAcknowledged	You tried to acknowledge a purchase twice	Duplicate logic in PurchaseHandler	Add a check before acknowledging
RequestThrottled	Rate limit hit	Too many API calls in a short window	Implement backoff, reduce call frequency
UnknownPayment	Purchase not found	Referencing a transaction that doesn’t exist	Confirm the purchase ID is current
CursorInvalid	Bad pagination cursor	Stale or corrupted cursor from GetProducts/GetPurchases	Request a fresh cursor
CursorInvalidLimit	Invalid limit parameter	Limit value out of accepted range	Use a standard limit (e.g., 10 or 25)
CursorNoMoreValues	End of paginated results	You’ve iterated through all available data	Stop paginating

Step by Step Integration Overview

This highrise payments API integration tutorial condenses the full workflow into seven steps. For complete Lua code examples, refer to the official Payments tutorial.

Step 1: Set up Highrise Studio. Install Unity, add the Highrise Studio plugin, and create a new project. The Getting Started guide walks through this in detail. If you prefer a template based approach, the Unity templates tutorial can speed things up.

Step 2: Create IWP products in the Creator Portal. Go to the Creation tab, select your World, open the In World Purchases section under the Monetization tab, and click Create. Fill in the product ID, name, and description. Set an image, enable “List For Sale,” and set the price in Gold.

Step 3: Write your server side PurchaseHandler. This script receives purchase notifications, grants items or rewards to the player, then calls AcknowledgePurchase to confirm fulfillment. Keep all fulfillment logic here, never on the client.

Step 4: Add a client side purchase trigger. This could be a button, an NPC interaction, or a zone trigger that calls PromptPurchase with your product ID.

Step 5: Test with built in test products. Use goldfish and eel as test product IDs in the Unity Editor before you upload your World. Gold won’t be deducted from your account during editor testing.

Step 6: Publish and test live. Upload your World and test the purchase flow in the actual app. Important: the World owner cannot purchase their own IWPs, so you’ll need a second account to test the live flow.

Step 7: Monitor your earnings. Check the Creator Exchange dashboard for incoming Earned Gold. Track conversion rates and adjust your product pricing based on what players actually buy.

Creating a Payment Handler Module

The PurchaseHandler is where the real work happens. Rather than scattering fulfillment logic across multiple scripts, experienced creators build a dedicated payment handler module that centralizes all purchase processing in one place.

Why Modularize?

A single World might sell consumable power ups, permanent cosmetic unlocks, and VIP access passes. Each product type requires different fulfillment logic. If you handle everything in one massive if/elseif block inside your PurchaseHandler callback, the code becomes fragile and hard to debug.

Instead, create a separate Lua module (a .lua file that returns a table of functions) dedicated to payment processing. Your main server script imports this module and delegates to it when the PurchaseHandler fires.

Structure of a Payment Handler Module

A clean payment handler module typically contains:

• A product registry that maps each product ID to a fulfillment function
• A fulfill function that looks up the product ID, runs the corresponding logic, and returns success or failure
• An acknowledge wrapper that calls AcknowledgePurchase only after successful fulfillment

This pattern keeps your server script short. The PurchaseHandler callback calls PaymentModule.fulfill(purchase, player), and the module handles the rest.

Handling Different Product Types

Consumables (like a health potion or bonus Gold) get consumed on use. Set wasConsumed = true when acknowledging. Permanent unlocks (like a VIP room or a special outfit) get consumed as false because the player retains them indefinitely.

The distinction matters for GetPurchases calls later. If a product was consumed, a player can buy it again. If it wasn’t consumed, your code should check purchase history before prompting a repeat purchase.

Practitioners on the Highrise Create Forum report that forgetting to set wasConsumed correctly is one of the most common bugs in payment integrations. A consumable acknowledged as non consumed means the player can never buy it again. A permanent unlock acknowledged as consumed means they might accidentally purchase it twice.

Persisting Currency and Purchases with Storage and Inventory

Purchases mean nothing if players lose them when they disconnect. Highrise provides two systems for persistence: the Storage API and the Inventory API. Which one you use depends on what you’re selling.

When to Use the Inventory API

If your IWP grants a tangible in game item (a weapon, a piece of furniture, a wearable), the Inventory API handles it. After the PurchaseHandler fires and you’ve validated the transaction, you call the Inventory API to add the item to the player’s inventory. The item then persists across sessions automatically because Highrise manages inventory server side.

When to Use the Storage API

If your IWP grants something abstract (like a currency balance, a rank, a score multiplier, or access to a premium zone), you need the Storage API. This API provides key value storage that persists across sessions for each player.

A common pattern:

1. Player buys 500 bonus coins (your custom in World currency, not Gold)
2. PurchaseHandler fires on the server
3. Server reads the player’s current coin balance from Storage
4. Server adds 500 to the balance and writes it back
5. Server acknowledges the purchase
6. Server updates the client’s UI via Network Values

Avoiding Data Loss

Always write to Storage before acknowledging the purchase. If you acknowledge first and then the Storage write fails, the player has been charged but received nothing, and the purchase is already marked complete. By writing first, a failed write means the purchase stays unacknowledged and can be retried.

Also consider that multiple purchases can fire in rapid succession. If two purchases try to read and write the same Storage key simultaneously, you can get a race condition where one write overwrites the other. Use a queue or sequential processing pattern in your PurchaseHandler to handle this.

For more on integrating persistent data with game systems, the guide on leaderboards and quests with Highrise APIs covers related Storage API patterns.

Creating and Attaching Lua Scripts for Payments

This section is for creators who understand the concepts but need the practical mechanics of getting scripts into their World.

Creating a Lua Script

In Highrise Studio (within Unity), right click in your Project panel, select Create, then choose Highrise Lua Script. Name it something descriptive: ShopServer for your server side handler, ShopClient for your client side trigger, PaymentModule for your modular handler.

Each script file opens in your text editor. The template usually includes basic lifecycle functions. For a payment script, you’ll strip most of that out and focus on the Payments API calls.

Attaching a Script to a GameObject

Every Lua script needs a home on a GameObject:

1. Select the GameObject in the Unity Hierarchy (for a shop, this might be an NPC or a UI canvas)
2. In the Inspector, click Add Component
3. Search for and add the Highrise Script component
4. Drag your .lua file into the script field, or select it from the dropdown

The critical decision is whether the script runs on the client or the server. In Highrise Studio, you designate this through the script’s execution context. Client scripts handle UI and player input. Server scripts handle data, fulfillment, and security sensitive operations.

For payment integration, you always need at least one server script (the PurchaseHandler) and one client script (the purchase trigger). They communicate through Highrise’s client server event system.

A Practical Example Layout

Consider a World with an NPC shopkeeper:

• NPC GameObject has a client script that detects when a player interacts with the NPC. On interaction, it shows a custom shop UI and, when the player picks a product, calls PromptPurchase.
• PaymentManager GameObject (can be an empty object in the scene) has a server script that registers the PurchaseHandler on initialization. When a purchase completes, it calls the payment handler module, fulfills the purchase via Inventory or Storage, and acknowledges the transaction.
• PaymentModule is a standalone Lua file (not attached to any GameObject) that exports fulfillment functions. The server script requires it via require("PaymentModule").

This separation keeps things clean and testable. If you need to add a second shop (say, a vending machine), you only need a new client script. The server side handler and module stay the same.

For a broader view of Lua scripting patterns in Highrise, the Lua leaderboard system example demonstrates similar module and event patterns in a non payment context.

Related APIs and Concepts

The Payments API doesn’t work in isolation. Several other systems connect to it.

Wallet API lets you send Gold from your World Wallet to players. After a player completes a quest or wins a tournament, you might reward them from the World Wallet using Wallet.TransferGoldToPlayer. This is server side only.

Inventory API handles granting in game items after a purchase. If your IWP is a special weapon or cosmetic, the Inventory API is how the player actually receives it.

Storage API persists data across sessions. Use it to save a player’s purchase state so they don’t lose access to something they bought if they disconnect.

Client Server Communication is the event model that connects your client side purchase prompts to server side handlers. Understanding how events flow between client and server is fundamental to any Payments API integration.

Network Values sync data between server and clients. If you need to update a player’s UI to reflect a new purchase, Network Values handle that broadcast.

Explore the Highrise community to see how other builders structure their in game economies and which products resonate with players.

Testing and Troubleshooting

Testing payment flows requires some specific knowledge that the official docs scatter across multiple pages. Here it is in one place.

Test product IDs: Use goldfish and eel to test purchases in the Unity Editor even if your World hasn’t been uploaded yet. Once your World is uploaded with IWP configured, switch to your actual product IDs.

Unity Editor limitation: Gold is not deducted from your account when testing in the editor. This means you can test the flow freely, but the financial side of the transaction isn’t real until you test in the app.

Owner restriction: You cannot buy your own IWPs. Create a second Highrise account to test the purchase flow after publishing.

False positive warning: The PromptPurchase callback can report a successful payment when one didn’t actually complete. Always rely on the server side PurchaseHandler for purchase validation.

Rate limiting: If you see RequestThrottled errors, you’re making too many API calls too quickly. Add delays between calls and avoid polling in tight loops.

Platform outages: If purchases suddenly fail across the board, check the Highrise status page before debugging your code. The problem might not be yours.

Storage debugging: If purchases seem to go through but players report missing items or currency, check your Storage write logic. A common issue is reading stale data because an async write hasn’t completed before the next read. Add logging around every Storage read and write to trace the exact sequence.

Practitioners on the Highrise Create Forum report confusion about monetization prerequisites. Threads like “Requirements to make a world monetized?” come up regularly. The short answer: create your IWP products in the Creator Portal, implement the Payments API in your Lua scripts, publish your World, and you’re live.

Security Best Practices for Payment Scripts

Payment code is the highest stakes code in your World. Someone will try to exploit it.

Never expose payment logic on the client. All fulfillment, acknowledgment, and Gold transfers must happen server side. Client events can be intercepted and manipulated by malicious players, so treat every client message as potentially forged.

Validate all server events. When your server receives a purchase notification, verify the product ID, the player reference, and the purchase object before granting anything.

Set maximum award limits. If you’re using the World Wallet to reward players, configure a maximum transfer amount in your World Wallet settings. This limits damage if someone finds an exploit.

Enable minimum balance alerts. The World Wallet supports alerts when your balance drops below a threshold. If your wallet drains unexpectedly, you’ll know.

Log everything. Record every transaction with timestamps, player IDs, product IDs, and amounts. If something goes wrong (or someone claims they didn’t receive a purchase), you’ll have a paper trail.

Protect your Storage writes. Since the Storage API persists currency balances and unlock states, a compromised write could give a player unlimited resources. Never let client input directly determine what gets written to Storage. The server should calculate all values independently based on the validated purchase.

The official security documentation is direct: if you transfer Gold from the World Wallet to player accounts, perform this operation on the server and do not involve the client directly.

How the Payments API Fits the Highrise Creator Economy

The Payments API isn’t just a technical feature. It’s one half of a creator monetization system that has already driven serious numbers. Highrise has surpassed 45 million users and $250 million in marketplace transactions as of late 2024. That marketplace activity signals a user base comfortable spending Gold, which is exactly the audience you’re building for.

Creators who build engaging Worlds can earn through both IWP sales and daily engagement payouts. The World Creator Awards program adds milestone bonuses on top, ranging from 100,000 Gold at 25,000 hours of player time up to 1 million Gold at the 1 million hours milestone.

The broader ecosystem supports your World building efforts in multiple ways. Submit item designs through Highrise Ideas or visual concepts through Highrise Concepts to build your reputation and contribute to the catalog that players buy from. The more integrated you are with the platform, the more visibility your Worlds get.

For the latest creator updates, feature announcements, and API changes that might affect your Payments integration, keep an eye on the Highrise blog.

Frequently Asked Questions

What happens if a purchase fails mid transaction?

If a purchase doesn’t complete, the PurchaseHandler won’t fire on the server, so no fulfillment occurs and no Gold is deducted from the player. The player can simply try again. If the PurchaseHandler fires but you encounter an error during fulfillment, don’t call AcknowledgePurchase. The system will treat the purchase as unresolved, and the player won’t be charged permanently.

Can I offer subscriptions through In World Purchases?

The Payments API documentation lists subscriptions as a supported product type. You’d create the subscription product in the Creator Portal and handle recurring access logic in your server scripts, checking purchase history with GetPurchases to verify active status.

How quickly does Earned Gold appear after a sale?

Earned Gold from IWP sales is deposited into your Creator Exchange balance after the transaction is acknowledged. The exact timing can vary, but it’s generally fast. Check the Creator Exchange dashboard to confirm.

What’s the difference between Gold and Earned Gold?

Gold is the virtual currency everyone uses in Highrise. Earned Gold is a subset of Gold that creators receive specifically from IWP sales or engagement payouts. Earned Gold can be spent like regular Gold, but it’s also eligible for cash out through the Creator Exchange. Regular Gold that you purchase or receive as gifts cannot be cashed out. The Earned Gold explainer covers this in detail.

Can I refund a purchase?

The Payments API doesn’t include a built in refund method. If a player requests a refund, you’d need to handle it through your own logic (e.g., revoking access and noting the transaction) or direct the player to Highrise support.

Do I need Highrise+ to use the Payments API?

No. The Payments API is available to all World creators through Highrise Studio. Highrise+ is a player subscription that affects engagement based payouts (because engagement is measured by Highrise+ subscriber time in your World), but it’s not a requirement for implementing IWP.

Why do I get InvalidProductId errors in testing?

If you’re using custom product IDs in the Unity Editor before uploading your World, they won’t resolve. Use the built in test IDs goldfish and eel for pre upload testing. After uploading, switch to the product IDs you created in the Creator Portal.

Does Highrise only support Lua for scripting?

Yes. All World logic in Highrise Studio is written in Lua. You cannot use C#, JavaScript, or any other language for gameplay scripting. The Unity editor is used for scene layout and asset management, but runtime behavior is Lua only. This keeps the sandbox secure and the barrier to entry low for new creators.

How do I persist custom currency or unlock states?

Use the Storage API for any data that needs to survive across sessions. Write purchase results to Storage immediately after fulfillment but before acknowledgment. This ensures that if the write fails, the purchase remains unacknowledged and can be retried without charging the player twice.

How do I see live examples of Worlds with Payments API integration?

Play published Worlds directly in Highrise to experience how other creators implement in game shops, unlock gates, and premium features. Studying working examples is one of the fastest ways to understand what players respond to.