Economy

Every balance and inventory change happens on the server. The client can read state and request a transaction, but it can never write a balance.

Platform wallet

The platform wallet holds the player’s SusaPlay coins, shared across games. Players earn coins by watching rewarded ads, and spend them anywhere on SusaPlay where a developer allows it.

var wallet = await SusaPlaySDK.Purchases.GetPlatformWallet();
if (wallet.Success)
{
    // Inspect wallet.Wallet for the current balance
}

Store catalogue

var store = await SusaPlaySDK.Purchases.GetStoreItems();

Items come from the economy config you defined in the Developer Portal. Each item has a money price, and a coin price when you allowed paying with coins:

foreach (var item in store.Items)
{
    if (item.directPurchaseEnabled)
        ShowBuyButton(item, $"${item.cashPrice.amount:0.00}");   // money

    if (item.walletPurchaseEligible)
        ShowCoinButton(item, item.coinPrice);                     // coins
}

Field	Meaning
`cashPrice`	The money price: `amount` and `currency` for display, `amountMinor` (e.g. `499`) for comparisons
`coinPrice`	The coin price, or `0` when the item cannot be bought with coins
`directPurchaseEnabled`	It can be bought with money now
`walletPurchaseEligible`	It can be bought with coins now

Disable the coin button while the player’s balance is below coinPrice. These fields need SDK 1.11.0; on older SDKs price carries the coin price.

Spending

var result = await SusaPlaySDK.Purchases.SpendPlatformWallet("sword_of_fire");

if (result.Success)
{
    GrantItemLocally("sword_of_fire");
}
else
{
    Debug.LogWarning(result.Error);
}

The server charges the item’s coin price; your game never sends a price. A spend is refused unless you allowed paying with coins for the item. Grant the item in your game only after Success is true. Never grant optimistically.

Real-money purchases

Checkout is handled by the shell. Your game starts the flow and awaits the outcome — which payment provider takes the money is a platform setting, and your game never names one.

// Buy a specific item
var purchase = await SusaPlaySDK.Purchases.StartDirectItemPurchase("starter_pack");

// Or top up the platform wallet
var topup = await SusaPlaySDK.Purchases.StartWalletTopupPurchase("coins_100");

Available top-up packs:

var packs = await SusaPlaySDK.Purchases.GetTopupPacks();

PurchaseResult:

Field	Type	Notes
`Success`	`bool`	True only when payment completed and rewards were credited
`Status`	`string`	`paid` (or the provider’s `done` or `successful`); `invalid-request` (no top-up pack ID); `canceled` or `dismissed` (the player canceled or closed checkout); `auth-dismissed` (a guest declined to sign in); `token-failed` (checkout could not start — `ErrorMessage` says why); `timeout`
`WalletScope`	`string`	`live` or `sandbox` — which wallet the balance landed in. Empty when checkout never opened
`Wallet`	object	Game wallet balance after the transaction
`PlatformWallet`	object	Platform wallet balance after the transaction
`ErrorCode`, `ErrorMessage`	`string`	Populated on failure

A durable item the player already owns is refused before checkout opens: token-failed, with ErrorMessage “Durable item is already owned”. Check the inventory before offering it:

var inventory = await SusaPlaySDK.Purchases.GetInventory(); // Items, Consumables
var used = await SusaPlaySDK.Purchases.ConsumeItem("health_potion", quantity: 1);

SpendPlatformWallet and ConsumeItem take an optional requestId: retrying with the same one never charges or consumes twice. The purchase call waits up to three minutes — a player has to move through a real checkout. Show a waiting state rather than blocking input.

Entitlements are granted by the payment webhook on the server, not by this return value. If the player closes the tab mid-checkout, the purchase can still complete. Re-read the wallet on the next session rather than assuming a cancelled checkout means no charge.

Sandbox

Every checkout method (StartDirectItemPurchase, StartWalletTopupPurchase) takes a sandbox flag, which requests the test lane:

await SusaPlaySDK.Purchases.StartDirectItemPurchase("starter_pack", sandbox: true);

The server decides whether to grant it. It is granted to platform admins and to a developer on their own games; every other caller transacts live whatever the flag says. A sandbox purchase credits a separate test wallet that never touches the live balance — WalletScope on the result tells you which one you are looking at, so a test purchase is never mistaken for one that failed to credit.

In-app purchases (iOS / Android)

Not supported. SusaPlay runs on WebGL, and the native store receipt-validation path has been removed. Every real-money purchase goes through the browser checkout described above.

An item that cannot be bought with money right now (its price tier is off sale or not set) gives token-failed before checkout opens; check directPurchaseEnabled before showing the button.StartPurchase() is obsolete since SDK 1.11.0. It names no item, and the platform refuses that: use StartDirectItemPurchase(itemId).

SDK 1.5.0 renamed the purchase API off the payment provider: StartXsollaPurchase is now StartPurchase and XsollaPurchaseResult is now PurchaseResult, with no deprecated aliases. A game still using the old names must be updated and rebuilt.

Getting Started

Integration

SDK

API

Platform wallet

Store catalogue

Spending

Real-money purchases

Sandbox

In-app purchases (iOS / Android)

​Platform wallet

​Store catalogue

​Spending

​Real-money purchases

​Sandbox

​In-app purchases (iOS / Android)

Platform wallet

Store catalogue

Spending

Real-money purchases

Sandbox

In-app purchases (iOS / Android)