> ## Documentation Index
> Fetch the complete documentation index at: https://docs.susaplay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Economy

> Platform wallet, store catalogue, and purchases

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 is shared across games. Players top it up with real money and spend it
anywhere on SusaPlay.

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

## Store catalogue

```csharp theme={null}
var store = await SusaPlaySDK.Purchases.GetStoreItems();
```

Items come from the economy config you defined in the Developer Portal.

## Spending

```csharp theme={null}
var result = await SusaPlaySDK.Purchases.SpendPlatformWallet("sword_of_fire");

if (result.Success)
{
    GrantItemLocally("sword_of_fire");
}
else
{
    Debug.LogWarning($"{result.ErrorCode}: {result.ErrorMessage}");
}
```

The price is read from the economy config inside the same transaction that debits the wallet, so
a price change mid-flight cannot be exploited.

Grant the item in your game only after `Success` is true. Never grant optimistically.

## Real-money purchases

Checkout is handled by the shell through Xsolla. Your game starts the flow and awaits the
outcome.

```csharp theme={null}
// 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:

```csharp theme={null}
var packs = await SusaPlaySDK.Purchases.GetTopupPacks();
```

`XsollaPurchaseResult`:

| Field                       | Type     | Notes                                                      |
| --------------------------- | -------- | ---------------------------------------------------------- |
| `Success`                   | `bool`   | True only when payment completed and rewards were credited |
| `Status`                    | `string` | `paid`, `canceled`, `timeout`                              |
| `PlatformWallet`            | object   | Balance after the transaction                              |
| `ErrorCode`, `ErrorMessage` | `string` | Populated on failure                                       |

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.

<Warning>
  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.
</Warning>

## Sandbox

Every purchase method takes a `sandbox` flag for testing against Xsolla's sandbox:

```csharp theme={null}
await SusaPlaySDK.Purchases.StartDirectItemPurchase("starter_pack", sandbox: true);
```

## In-app purchases (iOS / Android)

Native store receipt validation exists in the backend but is currently disabled. Real-money
purchases go through Xsolla for all platforms today.