Quick Start
Get a working integration with INVO Network in about 30 minutes, whether you ship a game or a platform. Follow these four steps.
🧪 Build against Sandbox first
Always start in Test mode at console.invo.network/test. Sandbox uses test payment cards. No real money moves. Once your integration is solid, switch the console to Live at console.invo.network for production.
Register Your Title
Create a developer account and register a sandbox title.
Copy Your SDK Key
Format ivsdk_test_<random> in test mode, ivsdk_live_<random> in production (older ivsdk_<random> keys keep working). Used as X-Game-Secret-Key on every API call.
Make Your First Call
A read against player balance to confirm your key works.
Go Live
Your sandbox title is copied to production for you. Swap your key + base URL, then set the title to Live yourself in the console.
Step 1: Register Your Title
Choose your environment and complete the registration wizard:
The wizard collects:
- 1.Title information: icon, cover image, name, platforms.
- 2.SDK Key: auto-generated. Format
ivsdk_test_<random>in test mode orivsdk_live_<random>in production; the prefix tells you which server the key belongs to. Server-side use only. - 3.Currency setup: branded currency name, symbol, transfer policy (allowed destinations).
- 4.Payout setup (optional): link a bank account so you can withdraw your developer revenue later.
Step 2: Make Your First API Call
Authentication is a single header: X-Game-Secret-Key. No login flow, no token refresh, no cookies. Send the header from your backend (server-side only).
Read a player balance (Sandbox)
// Sandbox base URL: https://sandbox.invo.network/sandbox
const SDK_KEY = process.env.INVO_SDK_KEY; // ivsdk_test_<random>
const r = await fetch(
'https://sandbox.invo.network/sandbox/api/player-balances/player/by-email/test@example.com',
{ headers: { 'X-Game-Secret-Key': SDK_KEY } }
);
if (r.status === 404) {
// Player has never interacted with your game yet: that's fine.
// The player auto-creates the first time they hit a writing endpoint
// (purchase-currency, purchase-item, claim-transfer, etc.).
console.log('No player record yet.');
} else {
console.log(await r.json());
}Sandbox vs Production base URLs
// Sandbox: test cards, no real money const SANDBOX_BASE = 'https://sandbox.invo.network/sandbox'; // Production: live transactions const PROD_BASE = 'https://invo.network'; // All endpoints share the same path suffix: // <BASE>/api/player-balances/player/by-email/<email> // <BASE>/api/item-purchases/purchase-item // <BASE>/api/transfers/initiate-transfer // etc.
Expected response (existing player)
{
"player": {
"player_id": 12345,
"player_name": "Test Player",
"player_email": "test@example.com",
"date_joined": "2024-12-01T10:00:00+00:00"
},
"balances": [
{
"currency_id": 1,
"currency_name": "Gold Coins",
"available_balance": "1000.00",
"reserved_balance": "0.00",
"total_balance": "1000.00"
}
],
"summary": {
"total_value": "1000.00",
"currency_count": 1,
"has_funds": true
},
"last_updated": "2024-12-09T12:34:56Z"
}Step 3: Explore Core Features
Once that first call works, build out from here:
💰 Currency Purchases
Players buy your branded currency with real money via hosted checkout. They pay your listed price; the card fee (3.5% + $0.15 on Open, 5.0% + $0.15 on Merchant of Record) is charged to you. Who the seller is and who handles tax: Tiers.
View Currency Purchase API →🛒 Item Purchases
Players spend their balance on items inside your title. 95% goes to you, 5% Invo network fee.
View Item Purchase API →🔄 Cross-Game Transfers
A player moves their own balance from one title to another in the network.
View Transfer API →🎁 Player-to-Player Sends
A player sends currency to another player by phone, same game or cross-game.
Your server mints the player's token with POST /api/sdk/player-token, passing player_email and player_phone. On phone_mismatch: true, call updatePlayerPhone (POST /api/sdk/players/phone) before the player sends; see Player Identity.
🔔 Day one: surface incoming money
Set this up before you go live. If you receive transfers/sends, set a webhook URL and subscribe to ["*"] (or at least transfer.claim_pending), then poll /api/transfers/inbound-pending to list what's waiting and badge it. Act on direction: "inbound" and dedupe on X-Invo-Idempotency-Key (never on transaction_id): a move between two players of your own title delivers both an inbound and an outbound copy. Skip this and incoming money silently never surfaces to your players.
Integration Best Practices
- •Server-side only. Never embed your SDK key in a Unity/Unreal/mobile build or browser code.
- •Idempotency. All write endpoints accept a
client_request_id. Pass a fresh UUID per logical action and reuse the same id on retry. A duplicate never applies twice: item purchases, transfers and sends answer409with a message (look the original up by its own read), and a partner payout request returns the payout already created. - •Test on Sandbox first. Sandbox is a fully isolated database with test-card-only payments.
- •HTTPS only. Plain-HTTP requests are rejected at the edge.
- •Store the
identity_idreturned when you register a player or mint a player token (balance reads do not carry it). It joins the same human across titles while their email and phone stay the same. It is derived from both, so it changes when the email or phone changes: store the new one when a response saysidentity_rekeyed: trueor onplayer.phone_changed(see Player Identity). - •Handle 5xx with retry. Retry a 5xx with the same
client_request_id: if the first attempt went through, the retry is refused as a duplicate instead of applying twice.