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, 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, explains how the pieces fit together, 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.

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.

You can browse the Highrise item catalog for inspiration on what kinds of products resonate with the community.

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.

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.

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.

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.

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).

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.

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.

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.

For creators just getting started with building Worlds, explore the Highrise community to see what other builders are creating and how they structure their in-game economies.

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.

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.

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.

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.

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.