# Invo Network API Documentation — Full Reference

Auto-generated from prerendered docs pages. Source: https://docs.invo.network

---

## Introduction

URL: https://docs.invo.network/docs/introduction

Learn how to get started with Invo Network API for cross-game currency transfers. Complete introduction guide for game developers.

Welcome to INVO Network The INVO Network API is the world's most comprehensive cross-game financial infrastructure, supporting 60M+ users with enterprise-grade security. Build secure value transfers, enable player-to-player transactions, monetize cross-game engagement, and boost your revenue with our battle-tested platform. What Makes INVO Network Different? Unlike traditional single-game payment systems, INVO Network creates a unified financial ecosystem across all your games. Players can transfer currency between games they play, send currency to friends across different games, and maintain their value even when switching between games in your portfolio. Core Capabilities Cross-Game Self-Transfers Move YOUR currency between different games you play. Perfect for portfolio management and cross-game progression. • SMS verification for security • Claim codes for receiving • Cross-game only transfers • 10% platform fee structure Player-to-Player Sends Send currency to OTHER players using phone numbers. Works within same game or across different games. • Phone-based recipient targeting • Automatic SMS delivery to recipients • Same-game and cross-game support • Automatic player account creation Currency Purchases Real money to virtual currency conversion with saved payment methods and fraud protection. • Secure card processing with 3D Secure • Saved payment methods • Real-time fraud detection • Comprehensive purchase history Scalable Player Management Real-time player balance queries supporting 60M+ users with batch processing and streaming APIs. • Batch operations (100K players) • Real-time balance streaming • Multi-game player tracking • Comprehensive activity history Enterprise Security Advanced security with SMS verification, velocity limits, spending controls, and real-time fraud detection. • SMS two-factor authentication • Circuit breakers for reliability • Comprehensive rate limiting • Real-time fraud prevention Developer Experience RESTful API with comprehensive examples for Unity, Unreal, and Godot. Get up and running in minutes. • Multi-engine code examples • Comprehensive documentation • Sandbox testing environment • Dedicated developer support Why Choose INVO Network? Unified Cross-Game Ecosystem • Players retain value when switching between your games • Cross-game community building and engagement • Shared revenue opportunities between games • Portfolio-level player lifetime value optimization Proven Revenue Impact • Reduce player churn through cross-game value retention • Increase player lifetime value across your portfolio • Generate revenue from transaction fees (10% total) • Enable new monetization strategies and features Enhanced Player Experience • Seamless value transfer between games • Player-to-player gifting and transactions • Automatic SMS notifications for all operations • Intuitive claim code system for receiving funds Enterprise-Grade Infrastructure • 99.9% uptime SLA with automatic failover • Supports 60M+ concurrent players • SOC 2 and PCI DSS compliance ready • Real-time monitoring and comprehensive analytics Understanding Transfers vs Sends Cross-Game Self-Transfers For moving your own currency between different games you play. • Who: You → Yourself in another game • Games: Must be different games (cross-game only) • Claiming: You manually enter the claim code • Use case: Portfolio management, moving funds between your games Player-to-Player Currency Sends For sending currency to other players via their phone number. • Who: You → Another player (identified by phone) • Games: Same game or different games • Claiming: Claim code automatically sent via SMS • Use case: Gifting, player trades, peer-to-peer transactions Quick Integration Example Here's a simple example of getting a player's balance with the INVO Network API: // Get player balance by email const response = await fetch( 'https://invo.network/api/player-balances/player/by-email/player@example.com', { headers: { 'X-Game-Secret-Key': 'YOUR_SDK_KEY' } } ); const result = await response.json(); // Example response: { "player": { "player_id": 12345, "player_name": "John Doe", "player_email": "player@example.com", "identity_id": "f3a1b8c0d4e5...", "date_joined": "2024-01-15T10:30:00Z" }, "balances": [ { "currency_id": 1, "currency_name": "Gold Coins", "available_balance": "1500.00", "reserved_balance": "100.00", "total_balance": "1600.00" } ], "summary": { "total_value": "1600.00", "currency_count": 1, "has_funds": true }, "last_updated": "2024-12-09T12:34:56Z" } Ready to Get Started? Explore the API Browse our comprehensive API documentation with examples for Unity, Unreal, and Godot. Quick Integration Start with player balance management and add cross-game features as your needs grow. Enterprise Support Get dedicated support, custom rate limits, and SLA guarantees for your production deployment. Trusted by Game Developers Worldwide Built for scale, designed for developers, optimized for revenue 60M+ Active Players 99.9% Uptime SLA 100K Batch Size 24/7 Enterprise Support

---

## Quick Start

URL: https://docs.invo.network/docs/quick-start

Get started with Invo Network in 5 minutes. Step-by-step guide to integrate cross-game currency transfers.

Quick Start Get a working integration with INVO Network in about 30 minutes. Follow these four steps. 🧪 Build against Sandbox first Always start in Sandbox at dev.console.invo.network . Sandbox uses test payment cards — no real money moves. Once your integration is solid, switch to console.invo.network for production. 1 Register Your Game Create a developer account and register a sandbox game. 2 Copy Your SDK Key Format ivsdk_<random> . Used as X-Game-Secret-Key on every API call. 3 Make Your First Call A read against player balance to confirm your key works. 4 Go Live Re-register on production and swap your key + base URL. Step 1: Register Your Game Choose your environment and complete the game registration wizard: 🧪 Sandbox dev.console.invo.network Test cards, no real money. 🚀 Production console.invo.network Live games, real-money transactions. The wizard collects: 1. Game Information: game icon, cover image, name, platforms. 2. SDK Key: auto-generated. Format ivsdk_<random> . 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 game 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_<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", "identity_id": "f3a1b8c0d4e5..." }, "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. View Currency Purchase API → 🛒 Item Purchases Players spend their balance on items inside your game. 90% goes to you, 10% Invo network fee. View Item Purchase API → 🔄 Cross-Game Transfers A player moves their own balance from one game 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. View Send API → 🔔 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. Skip this and incoming money silently never surfaces to your players. Webhooks & receiving money → 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 replay the same id on retry — duplicates return 409 with the original record. • 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_id returned on player records — it's the stable cross-game join key for the same human across the network. • Handle 5xx with retry. Idempotency-keyed requests are safe to retry on a 5xx; the first successful result is replayed. Next Steps Read the Sandbox Testing Guide for the full sandbox-vs-production map. Browse the API Overview for every endpoint with request/response schemas. Set up your Virtual Currency branding and transfer policy. Follow the Game Developer Integration Guide for end-to-end checkout integration.

---

## API Overview

URL: https://docs.invo.network/docs/api-overview

Complete overview of Invo Network API endpoints, authentication, and core concepts for cross-game currency integration.

INVO Network API Overview The INVO Network API gives game developers a unified ledger and payments infrastructure for virtual currency, real-money top-ups, item sales, cross-game transfers, and player-to-player sends. Server-to-server, REST, JSON, single-header auth. Two Environments INVO runs Production and Sandbox as fully isolated databases with independent SDK keys. Develop against Sandbox, cut over to Production when ready. 🚀 Production • Base URL: https://invo.network • Routes: /api/... • Real-money transactions • Console: console.invo.network 🧪 Sandbox • Base URL: https://sandbox.invo.network • Routes: /sandbox/api/... • Test cards only — no real money • Console: dev.console.invo.network Real-Money Top-ups • Players buy your branded currency with credit/debit cards • Hosted checkout — partners are out of scope for full PCI • Strong customer authentication (3DS) where required • Refund + chargeback handling with automatic balance debits Self-Transfers • A player moves their own currency between games they play • SMS PIN confirmation on the sender • Claim flow on the receiving game • Network fee split applied automatically Player-to-Player Sends • Send currency to another player by phone number • Same game or cross-game — recipient gets a claim SMS • SMS PIN confirmation on the sender • Velocity limits + fraud detection on every step Player Reads • Single-player balance lookup by email • Batch balance lookup (up to 100K emails per call) • Streaming reconciliation endpoint for nightly diffs • Cross-game stable join key ( identity_id ) Security & Reliability • Single-header auth ( X-Game-Secret-Key ) • Per-IP and per-key rate limiting with progressive penalties • Idempotency-keyed write endpoints (replay-safe) • Circuit breakers on every external dependency Core API Endpoints Player Balance Read player balances. Single, batch, or streaming. GET /api/player-balances/player/by-email/ {email} POST /api/player-balances/batch GET /api/player-balances/stream-all Currency Purchase Real-money top-ups, hosted checkout, payment confirmation. POST /api/checkout/sessions POST /api/currency-purchases/purchase-currency POST /api/currency-purchases/confirm-payment GET /api/currency-purchases/order-details Item Purchase Spend a player's branded currency on items inside your game. POST /api/item-purchases/purchase-item GET /api/item-purchases/player-purchase-history GET /api/item-purchases/order-details Self-Transfer (cross-game) A player moves their own balance from one game to another. POST /api/transfers/available-destinations POST /api/transfers/initiate-transfer POST /api/transfers/verify-sms POST /api/transfers/claim-transfer Player-to-Player Send Phone-based send to another player, same or different game. POST /api/currency-sends/initiate-send POST /api/currency-sends/verify-sms POST /api/currency-sends/claim-currency Withdrawals (developer revenue) Move developer revenue out of Invo to your bank. GET /api/withdrawals/available-balance POST /api/withdrawals/request GET /api/withdrawals/history Authentication Every server-to-server API call carries a single header. No login flow, no token refresh, no cookies. One-header authentication const SDK_KEY = process.env.INVO_SDK_KEY; // ivsdk_<random> // Production const r = await fetch( 'https://invo.network/api/player-balances/player/by-email/player@example.com', { headers: { 'X-Game-Secret-Key': SDK_KEY } } ); // Sandbox const r2 = await fetch( 'https://sandbox.invo.network/sandbox/api/player-balances/player/by-email/player@example.com', { headers: { 'X-Game-Secret-Key': SDK_KEY } } ); console.log(await r.json()); See Authentication for full details, including key rotation and error codes. Idempotency on writes Every write endpoint accepts a client_request_id in the body. Generate a UUID per logical action; replay the same id on retry. A duplicate returns 409 Conflict with the original record's identifiers. Replay-safe writes // Client generates a fresh UUID per checkout button click const clientRequestId = crypto.randomUUID(); const r = await fetch('https://invo.network/api/item-purchases/purchase-item', { method: 'POST', headers: { 'X-Game-Secret-Key': SDK_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ client_request_id: clientRequestId, player_email: 'player@example.com', item_id: 'sword_001', item_name: 'Iron Sword', item_quantity: 1, unit_price: '100.00', total_price: '100.00' }) }); // On 5xx or network failure: retry the SAME request body with the same // client_request_id. The first successful result is replayed; duplicates // return 409 with { transaction_id, order_id } for lookup. Rate Limits & Error Contract Rate limits • Balance reads: 1500 / minute • Item purchase: 60 / minute / player • Currency purchase: 20 / minute / player • Transfers / sends initiate: 10 / minute / player • 429 responses include retry_after seconds Error envelope { "error": "Human-readable message", "error_code": "MACHINE_READABLE_CODE", "error_id": "ERR_<yyyymmdd>_<hex>", "timestamp": "2024-12-09T12:34:56Z" } Capture error_id when reporting issues. We map it to the matching server log entry instantly. Single-Header Auth X-Game-Secret-Key on every call. Server-side only — never bundled into clients. Real-Time Processing Balance updates apply on commit. Webhooks deliver state changes to your backend in seconds. Built for Scale Pagination, batch reads, streaming reconciliation. Designed for portfolios with millions of players. Quick Integration Path 1 Register your developer account + game Sandbox first ( dev.console.invo.network ). Capture your ivsdk_… SDK key. 2 Configure your branded currency Name, symbol, transfer policy. 3 Wire up balance reads + item purchase Smallest end-to-end loop: top up via hosted checkout → read balance → spend on an item. 4 Add transfers + sends if your design needs them Optional. Same auth, same response envelopes. 5 Promote to Production Re-register at console.invo.network . Swap base URL + SDK key. Done.

---

## Authentication

URL: https://docs.invo.network/docs/authentication

Learn how to authenticate with Invo Network API using API keys and secure your game integration.

Authentication The INVO Network API authenticates server-to-server requests with a single header: X-Game-Secret-Key . Every game has its own SDK key issued at registration. Send the key on every API request. Server-to-Server Authentication Set the SDK key on every request. No login flow, no token refresh, no cookies. X-Game-Secret-Key: ivsdk_{your_sdk_key} Server-side only. Never embed your SDK key in client builds, mobile apps, or browser code. Game Server → Invo API Your game backend calls Invo with X-Game-Secret-Key. This is the only auth pattern game engines should use. Developer Console (Browser) The developer dashboard at console.invo.network uses session-based login for the human accessing the UI — separate from API auth. One Key Per Game Each registered game has a unique secret_key in the format ivsdk_<random>. Different games on the same account get different keys. Sandbox + Production Two fully isolated environments with independent SDK keys. Use /sandbox/api/... for testing, /api/... for production. Quick Example A complete authenticated call. Replace ivsdk_YOUR_SDK_KEY with the key from your game registration. Authenticated Request // Production const BASE_URL = 'https://invo.network'; // Sandbox: const BASE_URL = 'https://sandbox.invo.network/sandbox'; const SDK_KEY = process.env.INVO_SDK_KEY; // ivsdk_<random> const response = await fetch( `${BASE_URL}/api/player-balances/player/by-email/player@example.com`, { headers: { 'X-Game-Secret-Key': SDK_KEY } } ); const data = await response.json(); console.log(data); Server-Side Only Your SDK key authorises every API call as your game. Anyone holding it can move your players' balances. Treat it like a database password. ✅ Store in your server's environment variables / secrets manager ✅ Make API calls from your game backend, never directly from client builds ❌ Never commit it to source control ❌ Never bundle it into a Unity/Unreal/mobile build ❌ Never include it in HTML/JavaScript served to a browser Getting Your SDK Key SDK keys are issued automatically when you register a game. Choose the environment that matches your stage: 🚀 Production Register at: console.invo.network Live games, real-money transactions. 🧪 Sandbox (Testing) Register at: dev.console.invo.network Test with virtual cards. No real money. Independent database. 1 Create your developer account Email verification, password, profile, ToS acceptance. 2 Register your game Game registration wizard: art, name, genre, platforms, transfer policy. 3 Copy your SDK key Format: ivsdk_<random> . Shown in the game settings page; rotate any time it leaks. 4 Start making API calls Send X-Game-Secret-Key on every request from your game server. Core Endpoints A handful of endpoints cover most integrations. Auth header is the same on all of them. Common API Calls const SDK_KEY = process.env.INVO_SDK_KEY; const BASE = 'https://invo.network'; // Get player's currency balance (auto-creates if writing flow runs first) async function getPlayerBalance(playerEmail) { const r = await fetch( `${BASE}/api/player-balances/player/by-email/${encodeURIComponent(playerEmail)}`, { headers: { 'X-Game-Secret-Key': SDK_KEY } } ); return r.json(); } // Player buys an in-game item with their currency balance async function purchaseItem(payload) { const r = await fetch(`${BASE}/api/item-purchases/purchase-item`, { method: 'POST', headers: { 'X-Game-Secret-Key': SDK_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }); return r.json(); } // Player sends currency to another player by phone async function initiateSend(payload) { const r = await fetch(`${BASE}/api/currency-sends/initiate-send`, { method: 'POST', headers: { 'X-Game-Secret-Key': SDK_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify(payload) }); return r.json(); } Authentication Errors 401 — missing or invalid SDK key { "error": "missing X-Game-Secret-Key header", "error_code": "INVALID_GAME_SECRET" } Verify the header name is exactly X-Game-Secret-Key and the value is your full ivsdk_<random> string. 403 — game inactive Your game's status isn't live or testing . Check the developer console. 429 — rate-limited You've exceeded the per-IP or per-key request budget for that endpoint. Body includes a retry_after seconds value; back off accordingly. Rotating Your SDK Key Rotate a key from the developer console at any time. The new key is shown once after rotation — copy and update your environment variables before the old key is invalidated.

---

## Partner Credentials & Key Handling

URL: https://docs.invo.network/docs/partner-credentials

The three credentials every Invo integration needs (game_id, SDK secret_key, webhook signing secret), where each lives, the server-side player-token rule, webhook verification, and key rotation.

Partner Credentials & Key Handling Everything your integration needs comes down to three credentials and two rules . This page is the canonical reference for what each key is, where it lives, and how to handle it safely. Your tenant gets three things Credential Lives What it's for game_id Anywhere Your tenant id. Not secret. SDK secret_key ivsdk_… Server-side ONLY Sent as the X-Game-Secret-Key header to mint player tokens and for server-to-server calls. Webhook signing secret Server-side ONLY Used to verify the webhooks we send you. It is NOT sent in requests to us. Where to find them • game_id and the SDK secret_key — on the dashboard's Platform & Keys page (user menu, top-right → Platform & Keys → pick your game). The key has a reveal/copy affordance and a self-serve rotate. • Webhook signing secret — shown once when you create the webhook on the dashboard's Webhooks page (and again on each rotation). Store it then; it isn't retrievable later. Never put a secret in a frontend bundle Anything in a browser build (Vite/React, etc.) is world-readable. The ivsdk_… secret and the webhook signing secret are server-side credentials — they must never ship to the client. Two rules that matter 1. The browser never holds the SDK key Your server mints a short-lived player token ; the browser uses that for every /api/sdk/* call. POST /api/sdk/player-token Header: X-Game-Secret-Key: <SDK secret_key> // server-to-server ONLY Body: { "player_email": "user@example.com" } // player must exist in your tenant → { "token": "<player token>", // Authorization: Bearer <token> "expires_at": "...Z", // ~15-min lifetime, NO refresh "identity_id": "id_…" } // On a 401 from any /api/sdk/* call → mint a fresh token and retry. 2. Verify every webhook X-Invo-Signature: t=<ts>,v1=<hmac> is HMAC-SHA256 over the literal string "<timestamp>.<raw_body>" , keyed with your signing secret. Verify constant-time, reject if the timestamp is outside a 5-minute window, and de-duplicate on X-Invo-Idempotency-Key . Full reference + verify snippet: Receiving Webhooks . Web platforms: passkey step-up WebAuthn runs on your origin Web platforms enroll a passkey on login and approve high-value transfers/sends with an assertion. The ceremony runs in the browser on your web origin , which must match the relying-party ID configured for your tenant. You configure the domain yourself on the dashboard's Platform & Keys page — submit the RP ID and origins, prove domain ownership with a DNS TXT record, and step-up turns on when verification passes. Un-enrolled users fall back to SMS automatically. See Platform Step-Up (WebAuthn) . Key rotation Both keys rotate self-serve, both with a 7-day grace window • The SDK secret_key rotates from the dashboard's Platform & Keys page (user menu → Platform & Keys → your game → Rotate key). The old key keeps working for 7 days so your integration can cut over without downtime — the new key is shown once in a copy dialog, and the page banners the grace deadline. • The webhook signing secret rotates from the dashboard's Webhooks page, also with a 7-day grace window — deliveries are dual-signed (two v1= values) so you can deploy the new value without downtime. X-Invo-Secret-Version tells you which is current. • If a key is ever exposed, rotate it immediately from the console — don't wait on us. Never share keys in chat or commit them to a repo. Related: Authentication · player token · Receiving Webhooks · Platform Step-Up · Transfers · Sends

---

## Sandbox Testing

URL: https://docs.invo.network/docs/sandbox-testing

Test your integration in the isolated sandbox environment at sandbox.invo.network. Test cards, no real money.

Sandbox Testing The Invo Sandbox environment provides a safe testing space to integrate and validate your game's currency operations without affecting real player data or processing actual payments. Perfect for development, testing, and QA workflows. Safe Testing Environment Test all API operations without risk to production data or real financial transactions. Isolated Data Completely separate sandbox data that won't interfere with your production environment. Realistic Simulation Full API functionality with simulated payments, SMS verification, and transfer operations. Instant Setup Get started immediately with pre-configured test data and sample API keys. Full Feature Parity All production features available in sandbox for comprehensive testing coverage. Test Scenarios Built-in error scenarios and edge cases to validate your error handling logic. Sandbox Environment The INVO Network sandbox environment uses a separate base URL and requires the /sandbox prefix for all API routes. Test with fake payments, SMS, and crypto without real money. Production Environment Base URL: https://invo.network API Routes: /api/* and /auth/* Console: console.invo.network Payments: Real-money transactions. Sandbox Environment (Testing) Base URL: https://sandbox.invo.network API Routes: /sandbox/api/* Console: dev.console.invo.network Payments: Test cards only — no real money moves. Sandbox API call // Sandbox API call — same single-header auth as production const SDK_KEY = process.env.INVO_SDK_KEY; // ivsdk_<sandbox_key> 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 } } ); console.log(await r.json()); Sandbox vs Production: what changes • Path prefix. Sandbox is /sandbox/api/... ; production is /api/... . • SDK key. Different key per environment — sandbox keys do not work against production and vice versa. • Database. Fully isolated; sandbox players, balances, and transactions live in their own database. • Card processing. Sandbox accepts test cards only — no real money moves regardless of amount. • SMS verification. Sandbox sends through a test channel; verification codes are surfaced in the response and the developer console for QA convenience. Test Data & Scenarios The sandbox comes pre-loaded with test data to help you get started quickly: Test Players Create your own test players Register test accounts in the sandbox console Use sandbox console to manage test balances Example Test Data Email: your-test@example.com Create players via API or console Test Card Numbers Success 4242 4242 4242 4242 Always succeeds. Generic decline 4000 0000 0000 0002 Always declines. Insufficient funds 4000 0000 0000 9995 Card-issuer-side decline for insufficient funds. 3D Secure required 4000 0025 0000 3155 Triggers strong customer authentication challenge. Bank account linking (sandbox) Test bank-link credentials are surfaced in the developer console under Sandbox > Test Data . SMS Testing Test SMS verification flows without sending real SMS messages: SMS Testing Configuration // SMS verification in sandbox uses test mode // Use any phone number format for testing - no real SMS is sent // Example: Initiate transfer with test phone number { "from_player_email": "player@example.com", "to_player_email": "player@example.com", "from_game_secret": "your_game_secret", "to_game_secret": "target_game_secret", "amount": "50.00", "phone_number": "+1234567890" // Any valid format works in sandbox } // Verification codes in sandbox are displayed in the API response // or available in the sandbox console for testing Testing Checklist Use this checklist to ensure comprehensive testing of your integration: Basic Operations Get player balance Purchase currency Initiate cross-game transfer Verify SMS PIN Claim transfer Error Scenarios Invalid API key Player not found Insufficient balance Payment declined Rate limit exceeded Ready for Production? Once you've thoroughly tested your integration in sandbox, switch to production: • Update base URL: https://invo.network • Remove /sandbox prefix: Use /api/* instead of /sandbox/api/* • Use production credentials: Get your production game_secret from console.invo.network • Environment detection: Implement logic to switch between environments • Test with real cards. Real money will be charged in production. Environment Switcher // Environment configuration const INVO = { production: { baseURL: 'https://invo.network', apiRoute: '/api' }, sandbox: { baseURL: 'https://sandbox.invo.network', apiRoute: '/sandbox/api' } }; const env = process.env.NODE_ENV === 'production' ? 'production' : 'sandbox'; const cfg = INVO[env]; const SDK_KEY = process.env.INVO_SDK_KEY; // matching key for the env // Read a player's balance const url = `${cfg.baseURL}${cfg.apiRoute}/player-balances/player/by-email/${encodeURIComponent('test@example.com')}`; const r = await fetch(url, { headers: { 'X-Game-Secret-Key': SDK_KEY } });

---

## Game Developer Integration

URL: https://docs.invo.network/docs/game-developer-integration

End-to-end integration guide: signed checkout sessions, iframe/WebView, webhook events, Unity/Unreal/iOS/Android examples.

Game Developer Integration Guide Currency Purchase Integration End-to-end guide for adding INVO Network real-money top-ups to your game. The recommended pattern is signed checkout sessions : your backend mints a short-lived URL, you open it in an iframe or WebView, and the player completes the purchase on a hosted page. Card data never touches your servers. Don't put your SDK key in a URL Your SDK key is server-side credentials. URL parameters end up in browser history, server access logs, referrer headers, and crash reports. Always mint a session on your backend and open the returned checkout_url . The checkout session is a short-lived (15 minutes), single-use signed token. Replaying it after success returns a 409 — there's no value to an attacker who intercepts it. Overview Flow 1. Player clicks "Buy Currency" in your game ↓ 2. Game client tells your backend to mint a session ↓ 3. Your backend POSTs /api/checkout/sessions with X-Game-Secret-Key ↓ 4. Backend returns a signed checkout_url to the client ↓ 5. Client opens checkout_url in iframe / WebView ↓ 6. Player completes payment on the hosted page ↓ 7. Server-to-server webhook fires — your backend updates state ↓ 8. (Optional UX) postMessage hint refreshes UI immediately ✅ SAQ-A scope Card data stays on the INVO-hosted page. Your PCI scope is the lightest tier. Two backend calls Mint a session, listen for the webhook. That's it. Mobile-friendly Same URL works in WebView on iOS and Android. Prerequisites Before you start: Developer account. Sign up at console.invo.network (or dev.console.invo.network for sandbox). Game registered. Use the wizard in the developer console. SDK key. ivsdk_<random> , stored in your server secrets manager. Server endpoint your game can call to mint sessions on demand. Webhook receiver URL (recommended) — registered with Invo so we can deliver authoritative purchase events. Server-side only. Your SDK key authorises every API call as your game. Never bundle it into a Unity/Unreal/mobile build or browser code. Step 1 — Mint a session (backend) When the player clicks Buy, your game tells your backend "this user wants to buy $X of currency." Your backend posts to INVO and returns the checkout_url to the client. Node.js (Express) example // Your backend route — called by the game client app.post('/store/start-checkout', requireAuth, async (req, res) => { const { usdAmount } = req.body; const userEmail = req.user.email; const r = await fetch('https://invo.network/api/checkout/sessions', { method: 'POST', headers: { 'X-Game-Secret-Key': process.env.INVO_SDK_KEY, // ivsdk_<random> 'Content-Type': 'application/json' }, body: JSON.stringify({ player_email: userEmail, usd_amount: String(usdAmount), rail: 'platform', // optional, default 'platform' (card). Also: 'game' (regional/game-store), 'steam' success_url: 'https://yourgame.com/store/success', cancel_url: 'https://yourgame.com/store/cancel', metadata: { user_id: req.user.id, source: 'web_store' } }) }); if (!r.ok) { return res.status(502).json({ error: 'checkout session failed' }); } const { checkout_url, session_id, expires_at } = await r.json(); res.json({ checkout_url, session_id, expires_at }); }); The response carries a 15-minute single-use signed URL ( checkout_url , plus session_id , expires_at , expires_in_seconds ). Hand it to the client to open in a WebView/redirect or an iframe. usd_amount must be greater than 0 and at most 999.99 ; on sandbox the checkout_url host is sandbox.invo.network . Step 2 — Open the URL (web) Two ways to present the checkout URL — pick based on whether you need it embedded in-page: WebView / full-page redirect Works everywhere, no setup. Open checkout_url in a WebView or redirect the browser to it; on success the page redirects to your success_url . Recommended for most integrations. Embedded <iframe> Player never visibly leaves your page. Works out of the box — any https site may embed. When embedded, the page does not redirect your top window; listen for the INVO_CHECKOUT_COMPLETE postMessage. Embedding works by default — no setup needed. Any https site may frame the checkout page. This is safe because the page is bound to a signed session: a framer can't change the amount or recipient, card entry happens in the payment processor's own secure iframe (never your page), and 3-D Secure breaks out to a top-level window automatically. Optionally, ask INVO to restrict framing to your specific origin(s) (e.g. https://app.yourgame.com ) as extra hardening. Browser JavaScript (embedded iframe) async function buyCurrency(usdAmount) { // 1. Ask YOUR backend for a session const r = await fetch('/store/start-checkout', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ usdAmount }), credentials: 'include' }); const { checkout_url } = await r.json(); // 2. Open it in an iframe overlay const overlay = document.createElement('div'); overlay.style.cssText = 'position:fixed;inset:0;background:rgba(0,0,0,.75);z-index:99999;display:flex;align-items:center;justify-content:center'; const iframe = document.createElement('iframe'); iframe.src = checkout_url; iframe.allow = 'payment'; iframe.style.cssText = 'width:90%;max-width:480px;height:90vh;max-height:720px;border:0;border-radius:16px;box-shadow:0 25px 50px -12px rgba(0,0,0,.5)'; overlay.appendChild(iframe); document.body.appendChild(overlay); // 3. Listen for the UX postMessage hint // Validate the origin: invo.network in prod, sandbox.invo.network in sandbox. window.addEventListener('message', (event) => { if (event.origin !== 'https://invo.network') return; // sandbox: 'https://sandbox.invo.network' if (event.data?.type === 'INVO_CHECKOUT_COMPLETE') { // Fired on SUCCESS only. data = { status:'success', new_balance, currency_name, transaction_id } const { new_balance } = event.data.data; overlay.remove(); // Optimistic UI refresh; the authoritative source is the webhook below. updateBalanceUI(new_balance); } }); // Player cancellation isn't a postMessage — handle it with your own close/cancel // affordance on the overlay (and the session simply expires unused). } postMessage is a UX hint, not authoritative. It's not signed. Use it to refresh the UI optimistically. For the ledger-of-record source, listen for the purchase.completed webhook (Step 4) or re-read the player's balance from the API. Unity Unity Integration WebGL build For browser builds, drop the JS-side iframe code above into a .jslib plugin and call it from C# via SendMessage . // Assets/Plugins/InvoCheckout.jslib mergeInto(LibraryManager.library, { OpenInvoCheckout: function(checkoutUrlPtr) { var checkoutUrl = UTF8ToString(checkoutUrlPtr); var overlay = document.createElement('div'); overlay.id = 'invo-checkout-overlay'; overlay.style.cssText = 'position:fixed;inset:0;background:rgba(0,0,0,.75);z-index:99999;display:flex;align-items:center;justify-content:center'; var iframe = document.createElement('iframe'); iframe.src = checkoutUrl; iframe.allow = 'payment'; iframe.style.cssText = 'width:90%;max-width:480px;height:90vh;max-height:720px;border:0;border-radius:16px'; overlay.appendChild(iframe); document.body.appendChild(overlay); window.addEventListener('message', function(event) { if (event.data && event.data.type === 'INVO_CHECKOUT_COMPLETE') { var data = event.data.data || {}; var el = document.getElementById('invo-checkout-overlay'); if (el) el.remove(); if (data.status === 'success') { SendMessage('InvoPaymentManager', 'OnPurchaseSuccess', JSON.stringify(data)); } else { SendMessage('InvoPaymentManager', 'OnPurchaseFailed', JSON.stringify(data)); } } }); } }); // InvoPaymentManager.cs using System.Runtime.InteropServices; using UnityEngine; using UnityEngine.Networking; public class InvoPaymentManager : MonoBehaviour { [DllImport("__Internal")] private static extern void OpenInvoCheckout(string checkoutUrl); public async void BuyCurrency(decimal usdAmount) { // 1. Ask YOUR backend to mint a session string sessionUrl = await RequestCheckoutFromBackend(usdAmount); if (string.IsNullOrEmpty(sessionUrl)) return; // 2. Open it via the JSLIB OpenInvoCheckout(sessionUrl); } public void OnPurchaseSuccess(string json) { var data = JsonUtility.FromJson<PurchaseResult>(json); // Optimistic UI refresh; the authoritative source is your webhook handler Debug.Log($"Bought {data.currency_name} (new balance {data.new_balance})"); } public void OnPurchaseFailed(string json) { Debug.LogWarning("Checkout failed: " + json); } [System.Serializable] private class PurchaseResult { public string status; public string transaction_id; public string currency_name; public string new_balance; } // YOUR backend mints the session — never call /api/checkout/sessions from // a Unity build directly, because that would require shipping the SDK key. private async System.Threading.Tasks.Task<string> RequestCheckoutFromBackend(decimal usd) { var req = new UnityWebRequest("https://yourgame.com/store/start-checkout", "POST"); req.uploadHandler = new UploadHandlerRaw(System.Text.Encoding.UTF8.GetBytes("{"usdAmount":" + usd + "}")); req.downloadHandler = new DownloadHandlerBuffer(); req.SetRequestHeader("Content-Type", "application/json"); await req.SendWebRequest(); if (req.result != UnityWebRequest.Result.Success) return null; var resp = JsonUtility.FromJson<SessionResponse>(req.downloadHandler.text); return resp.checkout_url; } [System.Serializable] private class SessionResponse { public string checkout_url; public string session_id; public string expires_at; } } Mobile builds (iOS / Android) For Unity mobile, ask your backend for the checkout_url , then open it in UnityWebView or a platform-native WebView (see iOS / Android sections below). The flow is identical to web — the same hosted page handles everything. Unreal Unreal Engine Integration On the server side, your dedicated server (or backend service) calls POST /api/checkout/sessions . On the client, open the returned checkout_url via the platform's web browser widget. Below: a minimal C++ helper that asks your backend for a session. // MyGameStore.cpp — runs on your dedicated server / authority #include "Http.h" #include "Json.h" void UMyGameStore::RequestCheckoutSession(const FString& UserEmail, double UsdAmount, TFunction<void(FString)> OnUrl) { TSharedPtr<FJsonObject> Body = MakeShareable(new FJsonObject); Body->SetStringField("player_email", UserEmail); Body->SetStringField("usd_amount", FString::Printf(TEXT("%.2f"), UsdAmount)); Body->SetStringField("success_url", "https://yourgame.com/store/success"); Body->SetStringField("cancel_url", "https://yourgame.com/store/cancel"); FString BodyStr; auto Writer = TJsonWriterFactory<>::Create(&BodyStr); FJsonSerializer::Serialize(Body.ToSharedRef(), Writer); auto Request = FHttpModule::Get().CreateRequest(); Request->SetURL(TEXT("https://invo.network/api/checkout/sessions")); Request->SetVerb(TEXT("POST")); Request->SetHeader(TEXT("X-Game-Secret-Key"), GetEnvSecretKey()); // server-side env var Request->SetHeader(TEXT("Content-Type"), TEXT("application/json")); Request->SetContentAsString(BodyStr); Request->OnProcessRequestComplete().BindLambda( [OnUrl](FHttpRequestPtr, FHttpResponsePtr Response, bool bOk) { if (!bOk || !Response.IsValid()) { OnUrl(FString()); return; } TSharedPtr<FJsonObject> Json; auto Reader = TJsonReaderFactory<>::Create(Response->GetContentAsString()); if (FJsonSerializer::Deserialize(Reader, Json)) { OnUrl(Json->GetStringField("checkout_url")); } else { OnUrl(FString()); } }); Request->ProcessRequest(); } Pass the resulting URL to your client over a trusted RPC. The client opens it in a WebBrowser widget; the player completes payment; your server-to-server webhook handler updates state authoritatively. iOS iOS Integration (WKWebView) Use a WKWebView for hosted checkout. Apple App Store policy: digital goods generally require In-App Purchase — review with your counsel before shipping a WebView checkout in an iOS App Store build. // SwiftUI / UIKit import WebKit class CheckoutVC: UIViewController, WKScriptMessageHandler { private var webView: WKWebView! override func viewDidLoad() { super.viewDidLoad() let config = WKWebViewConfiguration() // postMessage from the hosted page comes through this handler config.userContentController.add(self, name: "INVO_CHECKOUT") webView = WKWebView(frame: view.bounds, configuration: config) view.addSubview(webView) Task { // Ask YOUR backend for a session URL let url = try await fetchCheckoutUrlFromBackend() self.webView.load(URLRequest(url: url)) } } func userContentController(_ controller: WKUserContentController, didReceive message: WKScriptMessage) { // The hosted page does: // window.webkit?.messageHandlers?.INVO_CHECKOUT?.postMessage({...}) guard let body = message.body as? [String: Any], let type = body["type"] as? String, type == "INVO_CHECKOUT_COMPLETE", let data = body["data"] as? [String: Any] else { return } if let status = data["status"] as? String, status == "success" { // Optimistic UI refresh. Authoritative source: your webhook handler. self.dismiss(animated: true) } } } Android Android Integration (WebView) Use a Chrome Custom Tabs flow or a hosted WebView . Like iOS, Google Play policy may require Play Billing for in-app digital goods — verify with your counsel. // Kotlin class CheckoutActivity : AppCompatActivity() { override fun onCreate(savedInstanceState: Bundle?) { super.onCreate(savedInstanceState) val webView = WebView(this).apply { settings.javaScriptEnabled = true addJavascriptInterface(InvoBridge { result -> runOnUiThread { // result is the parsed JSON object posted by the hosted page finish() } }, "InvoBridge") } setContentView(webView) lifecycleScope.launch { // Ask YOUR backend for the checkout URL val url = fetchCheckoutUrlFromBackend() webView.loadUrl(url) } } } // JS interface — the hosted page calls window.InvoBridge.onComplete(JSON.stringify(data)) class InvoBridge(private val onResult: (Map<String, Any?>) -> Unit) { @JavascriptInterface fun onComplete(json: String) { val parsed = JSONObject(json) // Forward to your activity / view-model } } Step 4 — Server-to-server webhook (authoritative) Once the payment confirms, INVO posts a purchase.completed event to your registered webhook URL. This is the authoritative signal — even if the client closed the WebView, lost connectivity, or never sent the postMessage. POST <your_webhook_url> Headers: X-Invo-Signature: t=<unix_timestamp>,v1=<hex_hmac_sha256> X-Invo-Event-Id: <uuid> # unique per delivery (changes on retry/replay) X-Invo-Idempotency-Key: <stable id> # stable across retries/replays — dedupe on THIS Content-Type: application/json Body: { "event_id": "evt_01HX...", "idempotency_key": "evt_01HX...", # stable; matches X-Invo-Idempotency-Key "event_type": "purchase.completed", "created_at": "2024-12-09T12:34:56Z", "tenant_id": "<your game_id>", "data": { "transaction_id": "txn_...", "order_id": "ord_...", "player_email": "player@example.com", "identity_id": "f3a1b8c0d4e5...", "usd_amount": "10.00", "currency_amount": "100", "currency_name": "Gold Coins", "metadata": { "user_id": "u_42", "source": "web_store" } // your create-session metadata, echoed back unchanged (all rails) } } Verify the HMAC signature with your tenant's webhook signing secret (issued separately during onboarding). Dedupe on X-Invo-Idempotency-Key — it is stable across retries and replays. Do not dedupe on X-Invo-Event-Id (unique per delivery, changes on every retry/replay). Return 2xx as quickly as possible — non-2xx responses trigger retries (30s, 2m, 10m, 1h, 6h, 24h, then dead). // Node.js / Express webhook handler import crypto from 'crypto'; const SIGNING_SECRET = process.env.INVO_WEBHOOK_SECRET; const TOLERANCE_SECONDS = 300; app.post('/webhooks/invo', express.raw({ type: 'application/json' }), (req, res) => { const sigHeader = req.header('X-Invo-Signature') || ''; const parts = Object.fromEntries(sigHeader.split(',').map(p => p.split('=', 2))); if (!parts.t || !parts.v1) return res.status(400).end(); if (Math.abs(Math.floor(Date.now()/1000) - parseInt(parts.t, 10)) > TOLERANCE_SECONDS) { return res.status(400).end(); } const expected = crypto.createHmac('sha256', SIGNING_SECRET) .update(`${parts.t}.`).update(req.body).digest('hex'); if (!crypto.timingSafeEqual(Buffer.from(parts.v1), Buffer.from(expected))) { return res.status(400).end(); } const idemKey = req.header('X-Invo-Idempotency-Key'); // stable across retries/replays if (await alreadyProcessed(idemKey)) { return res.status(200).json({ received: true, duplicate: true }); } const event = JSON.parse(req.body.toString('utf8')); await handleEvent(event); // your business logic res.status(200).json({ received: true }); }); Troubleshooting 401 INVALID_GAME_SECRET — your X-Game-Secret-Key header is missing, malformed, or doesn't match the environment (sandbox vs production). 409 SESSION_ALREADY_CONSUMED — this session URL has already been consumed. Mint a new one. 410 SESSION_EXPIRED — the 15-minute TTL elapsed. Mint a new one. postMessage never arrives — check the iframe origin's CSP / sandbox attributes. The hosted page posts from the checkout origin — invo.network in production, sandbox.invo.network in sandbox (NOT the console host); verify your event listener is mounted before the iframe loads and that your origin check matches the right environment. Webhook signature mismatch — you must HMAC over the raw request bytes, not a re-serialised JSON. Use a raw body parser. Webhook missing — verify your endpoint returns 2xx and is registered in the developer console. We retry on backoff (30s → 24h) before marking dead.

---

## Unity SDK

URL: https://docs.invo.network/docs/unity-sdk

Complete documentation for the InvoSDK Unity plugin. Learn how to integrate in-game currency purchases, item marketplace, player-to-player transfers, and cross-game currency sends in your Unity game.

Unity SDK The official InvoSDK plugin for Unity enables seamless integration with the Invo Network platform for in-game currency management, item purchases, player-to-player transfers, and cross-game currency sends. Unity 6 (6000.0+) Compatible The InvoSDK plugin is built for Unity 6 with full C# async/await support, pre-built UI components, and Editor tools for rapid integration. Quick Integration - Get Started in 30 Minutes The InvoSDK Unity plugin is available on GitHub and designed for rapid integration. Get your game connected to the Invo Network in as little as 30 minutes. View on GitHub Easy Installation Copy to Assets folder and configure via Setup Wizard Pre-built UI Production-ready UI components you can customize Async/Await Modern C# async patterns throughout Editor Tools Setup Wizard, Test Purchase, Balance tools Core Features Currency Purchases Allow players to buy in-game currency with real money via secure Invo Payments integration. Item Marketplace Full catalog management with categories, rarities, discounts, and featured items. Cross-Game Transfers Enable players to transfer currency to other games in the Invo Network ecosystem. SMS Verification Secure player-to-player transfers with SMS PIN verification. Installation Requirements Unity 6 (6000.0+) .NET Standard 2.1 Newtonsoft.Json (com.unity.nuget.newtonsoft-json) An Invo developer account Step 1: Download the SDK Clone the InvoSDK from GitHub: git clone https://github.com/Invo-Technologies/Invo-unity-sdk.git Step 2: Copy SDK Files Copy the following into your Unity project's Assets folder: YourProject/ └── Assets/ ├── InvoSDK/ ← Copy this folder ├── APIManager.cs ← Copy this file └── Resources/ └── InvoSDKConfig.asset ← Auto-created by Setup Wizard Step 3: Install Dependencies Open Window → Package Manager and install: com.unity.nuget.newtonsoft-json Step 4: Run Setup Wizard The Setup Wizard opens automatically on first import. You can also access it via: 1. Open your project in Unity Editor 2. Go to InvoSDK → Setup Wizard in the menu 3. Enter your SDK Key, Game ID, and other settings 4. Click Save to create your configuration Configuration The SDK uses a ScriptableObject for configuration, stored at Assets/Resources/InvoSDKConfig.asset : Field Type Description sdkKey string Your Invo API secret key gameId string Your unique game identifier gameName string Display name for your game playerEmail string Default player email (for testing) playerPassword string Sandbox login password playerPhone string Player phone for SMS verification gameCurrencyName string Name of your in-game currency useProduction bool Toggle between sandbox/production Security Warning Never ship sdkKey in client builds. Store server-side for production deployments. Quick Start Access the API manager anywhere in your code using the singleton pattern: Get Player Balance using InvoSDK; // Get player's current balance await APIManager.Instance.GetPlayerBalanceAsync( email: "player@email.com", onSuccess: (response) => { foreach (var balance in response.balances) { Debug.Log($"{balance.currency_name}: {balance.total_balance}"); } }, onError: (error) => Debug.LogError(error) ); Purchase an Item using InvoSDK; await APIManager.Instance.PurchaseItemAsync( playerEmail: "player@email.com", playerName: "PlayerOne", itemId: "sword_001", itemName: "Legendary Sword", quantity: 1, unitPrice: 9.99f, totalPrice: 9.99f, onSuccess: (response) => { Debug.Log($"Purchase successful! Transaction: {response.transaction_id}"); }, onError: (error) => Debug.LogError(error) ); Fetch Game Items Catalog using InvoSDK; await APIManager.Instance.GetGameItemsAsync( onSuccess: (response) => { foreach (var item in response.items) { Debug.Log($"{item.item_name}: ${item.price_usd}"); } }, onError: (error) => Debug.LogError(error) ); API Reference Method Endpoint Description GetPlayerBalanceAsync /player-balances/player/by-email/ {email} Get player balance GetGameItemsAsync /v1/game-items/list Fetch game item catalog PurchaseItemAsync /item-purchases/purchase-item Purchase an item GetAvailableDestinationsAsync /currency-sends/available-destinations List transfer destinations InitiateSendAsync /currency-sends/initiate-send Start currency send VerifySmsAsync /currency-sends/verify-sms Verify SMS for sends ClaimCurrencyAsync /currency-sends/claim-currency Claim received currency API Environments Sandbox (Development) Host: https://sandbox.invo.network API: /sandbox/api/* Auth: /sandbox/auth/* Console: dev.console.invo.network Use for development and testing. No real money. Production (Live) Host: https://invo.network API: /api/* Auth: /auth/* Console: console.invo.network Live games only. Real money transactions. Pre-built UI Components The SDK includes production-ready UI components in Assets/InvoSDK/Scripts/UI/ : Item Purchase Panel Grid display with item cards and purchase confirmation Featured Items Daily and weekly featured item showcases Transfer Wizard 4-step currency transfer flow with SMS verification Send Currency Panel Player-to-player send interface Window Manager Panel-based navigation system Verification Input SMS code input component Editor Tools Access these tools from the Unity menu under InvoSDK : Setup Wizard Configure all SDK settings, quick links to documentation and console. InvoSDK → Setup Wizard Item Catalog Manage items, prices, discounts, and categories. InvoSDK → Item Catalog Test Purchase Test currency purchases with pre-configured payment methods. InvoSDK → Test Purchase Player Balance Check player balances during development. InvoSDK → Player Balance Troubleshooting Issue Solution "Config not found!" Ensure InvoSDKConfig.asset exists in Assets/Resources. Run Setup Wizard. "Player email not set" Set playerEmail in config or pass email directly to API methods. JSON parse errors Verify Newtonsoft.Json package is installed and included in build. 401/403 errors Check SDK key is correct. Verify using correct environment. Balance not updating Check balancePollInterval setting. Verify network connectivity. Resources Additional documentation and support channels GitHub Repository Source code, README, and releases Quick Start Guide General API integration guide Authentication SDK key header — server-side use Sandbox Testing Test environment guide

---

## Unreal Engine SDK

URL: https://docs.invo.network/docs/unreal-sdk

Complete documentation for the InvoSDK Unreal Engine plugin. Learn how to integrate in-game currency, item purchases, and player transfers in your Unreal Engine game.

Unreal Engine SDK The official InvoSDK plugin for Unreal Engine enables seamless integration with the Invo platform for in-game currency management, item purchases, and player-to-player transfers. Unreal Engine 4.27+ & 5.x Compatible The InvoSDK plugin supports both Unreal Engine 4.27+ and Unreal Engine 5.x with full Blueprint and C++ integration. Quick Integration - Get Started in 30 Minutes The InvoSDK Unreal plugin is available on GitHub and designed for rapid integration. Get your game connected to the Invo Network in as little as 30 minutes. View on GitHub Easy Installation Drop into your Plugins folder and go Blueprint Support Full Blueprint integration for visual scripting C++ Native Direct C++ API for maximum control Pre-built UI Ready-to-use UMG widget components Installation Prerequisites Unreal Engine 4.27+ or Unreal Engine 5.x Windows 64-bit development environment Visual Studio 2019 or later (for C++ development) An Invo developer account Step 1: Download the Plugin Download the latest InvoSDK plugin from the Invo Developer Console or clone from GitHub: git clone https://github.com/Invo-Technologies/invo-unreal-sdk.git Step 2: Install the Plugin Copy the InvoSDK folder into your project's Plugins directory: YourProject/ ├── Content/ ├── Source/ └── Plugins/ └── InvoSDK/ ← Place here ├── Source/ ├── Content/ └── InvoSDK.uplugin Step 3: Enable the Plugin 1. Open your project in Unreal Editor 2. Go to Edit → Plugins 3. Search for "InvoSDK" and enable it 4. Restart the editor when prompted Configuration The setup wizard automatically creates an InvoSDKConfig asset on first launch. Configure it with your credentials: Field Description Required sdkKey Your Invo API secret key Yes gameId Your unique game identifier Yes gameName Display name for your game Yes playerEmail Current player's email address Yes useProduction Toggle between production/sandbox Yes gameIconUrl URL to your game icon No gameCurrencyName Name of your in-game currency No Security Warning Never ship sdkKey in client builds. Use server-side authentication for production deployments. Blueprint Integration The SDK provides full Blueprint support for visual scripting. Here's how to make an API request: Making an API Request 1. Right-click in your Blueprint and search for "Invo Request" under InvoSDK | API 2. Configure the request parameters (Base URL, Endpoint, Headers, Body, Method) 3. Connect the OnSuccess and OnFail execution pins to your handlers Blueprint Node Configuration Input Parameters: Base URL - API host URL Endpoint - API endpoint path Headers - HTTP headers map Body - Request body (JSON) Method - GET, POST, PUT, DELETE Output Delegates: OnSuccess - Called on 2xx response OnFail - Called on error/non-2xx Delegate Parameters: ResponseContent - Raw response StatusCode - HTTP status bWasSuccessful - Success flag JsonObject - Parsed JSON JSON Helper Functions Use the InvoSDK | JSON category for parsing JSON responses in Blueprints: GetStringField Extract a string value from JSON GetIntegerField Extract an integer value from JSON GetBoolField Extract a boolean value from JSON GetObjectsArray Extract an array of JSON objects C++ Integration For maximum control, use the C++ API directly. Include the necessary headers and link against the InvoSDK module. Include Headers #include "InvoSDKApiManager.h" #include "InvoSDKJsonHelpers.h" Example: Fetch Player Balance // IMPORTANT: This must run on your dedicated server / authority — never on a // shipped client build. The SDK key authenticates as your game. void AMyActor::FetchPlayerBalance(const FString& PlayerEmail) { TMap<FString, FString> Headers; Headers.Add(TEXT("X-Game-Secret-Key"), GetEnvSdkKey()); // server-side env UInvoSDKApiManager* Request = UInvoSDKApiManager::InvoRequest( this, TEXT("https://sandbox.invo.network"), FString::Printf(TEXT("/sandbox/api/player-balances/player/by-email/%s"), *FGenericPlatformHttp::UrlEncode(PlayerEmail)), Headers, TEXT(""), EInvoHttpMethod::GET ); Request->OnSuccess.AddDynamic(this, &AMyActor::OnBalanceReceived); Request->OnFail.AddDynamic(this, &AMyActor::OnRequestFailed); Request->Activate(); } void AMyActor::OnBalanceReceived( const FString& Content, int32 StatusCode, bool bSuccess, const FJsonObjectWrapper& Json) { // Parse the response using JSON helpers FString PlayerEmail = UInvoSDKJsonHelpers::GetStringField(Json, TEXT("player_email")); int32 Balance = UInvoSDKJsonHelpers::GetIntegerField(Json, TEXT("balance")); UE_LOG(LogTemp, Log, TEXT("Player %s balance: %d"), *PlayerEmail, Balance); } void AMyActor::OnRequestFailed( const FString& Content, int32 StatusCode, bool bSuccess, const FJsonObjectWrapper& Json) { UE_LOG(LogTemp, Error, TEXT("Request failed [%d]: %s"), StatusCode, *Content); } Example: Purchase Item void AStoreManager::PurchaseItem(const FString& ItemId, int32 Quantity) { // Build JSON body TSharedPtr<FJsonObject> JsonBody = MakeShareable(new FJsonObject); JsonBody->SetStringField(TEXT("itemId"), ItemId); JsonBody->SetNumberField(TEXT("quantity"), Quantity); FString BodyString; TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&BodyString); FJsonSerializer::Serialize(JsonBody.ToSharedRef(), Writer); TMap<FString, FString> Headers; Headers.Add(TEXT("X-Game-Secret-Key"), GetEnvSdkKey()); // server-side env Headers.Add(TEXT("Content-Type"), TEXT("application/json")); UInvoSDKApiManager* Request = UInvoSDKApiManager::InvoRequest( this, TEXT("https://sandbox.invo.network"), TEXT("/sandbox/api/item-purchases/purchase-item"), Headers, BodyString, EInvoHttpMethod::POST ); Request->OnSuccess.AddDynamic(this, &AStoreManager::OnPurchaseSuccess); Request->OnFail.AddDynamic(this, &AStoreManager::OnPurchaseFailed); Request->Activate(); } API Environments Sandbox (Development) Host: https://sandbox.invo.network API: /sandbox/api/* Auth: /sandbox/auth/* Console: dev.console.invo.network Use for development and testing. No real money. Production (Live) Host: https://invo.network API: /api/* Auth: /auth/* Console: console.invo.network Live games only. Real money transactions. Pre-built UI Components The SDK includes ready-to-use UMG widgets located in Content/UI/ and Content/Widgets/ : Daily Deals Daily rotating offers display Featured Items Showcase featured items and bundles Item Purchase Purchase confirmation flow Send Currency Player-to-player send flow Transfer Currency Cross-game transfer interface SMS Verification Two-factor verification widget Troubleshooting Issue Cause Solution "Config not found!" InvoSDKConfig asset missing Create and configure InvoSDKConfig asset "Player email not set!" Empty playerEmail in config Set playerEmail in config or API call 401 Unauthorized Invalid/expired token Re-authenticate and refresh token 403 Forbidden Game inactive or wrong environment Verify the SDK key matches the environment (sandbox vs production) and the game is set to live or testing Request timeout Network issues Verify connectivity and endpoint URL Enable Debug Logging Add the following to your DefaultEngine.ini : [Core.Log] LogTemp=Verbose Resources Additional documentation and support channels GitHub Repository Source code, issues, and releases Quick Start Guide General API integration guide Authentication SDK key header — server-side use Sandbox Testing Test environment guide

---

## Web / TypeScript SDK

URL: https://docs.invo.network/docs/web-sdk

Official Invo Web SDK for web games, storefronts, and dashboards. Install @invonetwork/web-sdk to add currency purchase, item purchase, and passkey-verified sends/transfers to any web or Node app.

Web / TypeScript SDK @invonetwork/web-sdk is the official first-party SDK for integrating Invo into web platforms — web games, storefronts, and dashboards. It's the web analog of the Unity and Unreal plugins: a typed, versioned npm package that wraps Invo's currency purchase, item purchase, and passkey-verified send/transfer flows. Not using a game engine? Start here. If you're building on the web (React, Vue, plain JS, or any Node backend) rather than Unity or Unreal, this SDK is your integration path. Published on npm under the Invo-owned @invonetwork org. Install and call in minutes npm install @invonetwork/web-sdk — Node ≥ 18. View on npm and GitHub . Currency Purchase Hosted checkout — real money to game currency, no payment UI to build Item Purchase Spend existing game currency on in-game items Sends & Transfers Move currency between players, approved by passkey Passkeys WebAuthn enroll/approve — the web alternative to SMS PINs Install Terminal npm install @invonetwork/web-sdk Requires Node ≥ 18 on the server (uses the global fetch ). Ships ESM + CJS + TypeScript types. Backend not in Node? Use the first-party Python SDK ( pip install invonetwork ) for the server half — same endpoints and webhook scheme — and keep this package for the browser. Two entry points (the game secret never reaches the browser) @invonetwork/web-sdk/server Runs on your backend (Node ≥ 18). Holds the game secret . Mints player tokens; initiates sends/transfers; currency purchase; item purchase. @invonetwork/web-sdk Runs in the browser. Holds only a short-lived player token . Passkey enroll, approve, self-claim, device link. Never import /server into browser code — it carries the game secret. The two entries are built separately for exactly this reason. Get your account & game secret Sign up, create your game, and copy its credentials (the game secret plus your WebAuthn RP ID / origins) in the Invo console for the environment you're building against: Environment Console API baseUrl Testing / sandbox https://dev.console.invo.network https://sandbox.invo.network/sandbox Production https://console.invo.network https://invo.network Build and test on sandbox first, then switch to production for launch. Each environment has its own game secret — keep it server-side only and never mix them. baseUrl must be https:// ( http://localhost is allowed for local dev). Quick start 1. Server — mint a player token server.ts import { InvoServer } from "@invonetwork/web-sdk/server"; const invo = new InvoServer({ gameSecret: process.env.INVO_GAME_SECRET!, // server-side ONLY baseUrl: "https://sandbox.invo.network/sandbox", // prod: https://invo.network }); // Hand this short-lived (~15 min), game-scoped token to the browser. const { token } = await invo.mintPlayerToken({ playerEmail: "p@example.com" }); 2. Browser — run a passkey flow client.ts import { InvoClient } from "@invonetwork/web-sdk"; const invo = new InvoClient({ token, // fetched from your backend baseUrl: "https://sandbox.invo.network/sandbox", // Optional: auto re-mint + retry once if the token expires mid-session. refreshToken: () => fetch("/invo/token", { method: "POST" }).then(r => r.json()).then(j => j.token), }); await invo.enrollPasskey(); // once per user await invo.approveSend(transactionId); // or approveTransfer(...) Two integration modes (v1.0+). Browser-direct (above) points baseUrl at the INVO API — ask INVO to CORS-allow your origin. Or run behind your proxy : set baseUrl to your own backend (which injects the real player token server-side) and give the browser a session token — the INVO token never reaches the browser, and no CORS/security-posture change is needed. Same SDK either way. Lowest-risk first step: adopt just linkDevice (additive, no refactor). To run the game-secret writes behind your proxy too (so the secret leaves the browser), there's a drop-in InvoServer router at examples/proxy-server.ts . Its actor resolver is pluggable: session (one login = one player) for real partners, or a trusted first-party mode (caller names playerEmail , guarded by a shared secret) for a dashboard/test rig that impersonates arbitrary players. Currency purchase (real money in) Server-side, no passkey. The recommended path is hosted checkout — Invo's page handles the card processor and 3-D Secure, so you never touch card data. Open the returned URL via redirect, WebView, or an <iframe> . Grant currency off the purchase.completed webhook. server.ts const { checkoutUrl, sessionId } = await invo.createCheckout({ playerEmail: "p@example.com", usdAmount: "20.00", // USD, 0 < x ≤ 999.99 rail: "platform", // optional: "platform" | "game" | "steam" metadata: { yourOrderId: "ord_42" }, // echoed on the purchase.completed webhook (all rails) }); // → send the browser to checkoutUrl (single-use, ~15 min) See the Currency Purchase API for the direct rail selector, 3-D Secure, and order status. Item purchase (spend game currency) Spend the currency a player already owns to buy an in-game item — a balance debit, server-side only, no passkey or real money. Amounts are in game-currency units . Grant the item off the item.purchased webhook; Invo debits currency, your game owns the catalog. server.ts const item = await invo.purchaseItem({ clientRequestId: crypto.randomUUID(), // idempotency key, unique per game playerEmail: "p@example.com", playerName: "P", itemId: "sword_001", itemName: "Legendary Sword", itemQuantity: 1, // integer 1..1000 unitPrice: "100.00", // > 0 and ≤ 999999.99 totalPrice: "100.00", // must equal unitPrice × itemQuantity (±0.01) }); // item.status === "success", item.newBalance, item.transactionId, item.orderId Duplicates throw 409 ( err.isDuplicateRequest ); insufficient balance throws 400 ( err.isInsufficientBalance ). Full contract: Item Purchase . Player balance Read a player's currency balances server-side (game-secret), by email or player id. server.ts const { balances, summary } = await invo.getPlayerBalance({ playerEmail: "p@example.com" }); // balances: [{ currencyName, availableBalance, reservedBalance, totalBalance, currencySymbol }] // or look up by id: invo.getPlayerBalance({ playerId: 12345 }) Full field reference: Get Player Balance . Sends & transfers (move currency between players) Initiate on the server, then have the sender approve in the browser with their passkey (or an SMS PIN if they're not enrolled). The recipient claims with their own passkey, or via a claim code. Where can I send? (v0.7.0+). Populate the destination picker with one player-token call — client.getDestinations({ direction: "transfer" | "send" }) — which returns every reachable game with display metadata inline (name, icon, currency name/symbol, min/max limits), plus the source game/currency and transferMode . No per-game lookup, no backend round-trip. What do I have? (v0.8.0+). client.getBalance() returns the player's balances for this game (player-token) — rows carry currencySymbol / currencySymbolUrl and availableBalance / reservedBalance / totalBalance (decimal strings), plus totalValue / hasFunds . A player who hasn't transacted here yet returns an empty list (show 0.00), not an error. Cross-game portfolio lives on the wallet app, not the game SDK. transfer flow // SERVER — initiate, then branch on how the sender must verify const t = await invo.initiateTransfer({ clientRequestId: crypto.randomUUID(), sourcePlayerName: "P", sourcePlayerEmail: "p@example.com", sourcePlayerPhone: "+15555550100", targetPlayerEmail: "q@example.com", targetPlayerPhone: "+15555550111", targetGameId: 123456, amount: "50", }); // t.verificationMethod: "in_app" (passkey) | "sms" (PIN fallback) | undefined (guardian, HTTP 202) // BROWSER — sender approves; recipient self-claims (fall back to claim code if not enrolled) const approved = await invo.approveTransfer(t.transactionId); // returns claimCode await invo.confirmReceiptTransfer(t.transactionId); // or use approved.claimCode initiateSend is the same shape with sender* / receiver* + receivingGameId . See Transfers and Sends . "You have X to collect". Two ways to list a player's pending items: • Browser (v0.6.0+): client.getPendingCollect() — the logged-in player's own list (player-token, PII-free). Each row's kind : identity_gate → call approve* , receiving_confirm → call confirmReceipt* . • Server (v0.4.0+): server.getInboundPending({ playerEmail | playerPhone }) — richer, includes toPhone / toIdentityId for routing a notification. Match toPhone to the player. Incoming from another game? Those rows come back as kind: "receiving_confirm" — render both kinds or a collect UI that only shows identity_gate will miss all inbound. The browser list is scoped to the token's player, so mint the token for the recipient . Both methods pair with the transfer.claim_pending webhook. Holds (v0.6.0+). An approve/claim can return an HTTP 202 hold instead of success — check result.holdReason ( RISK_HOLD , GUARDIAN_APPROVAL_PENDING , and on confirm-receipt RECIPIENT_IDENTITY_PENDING ); success has no holdReason . Terminal guardian outcomes throw. Completion, recovery & phone-share (server, v1.1.0+). Alongside the passkey path, InvoServer covers the non-passkey flows: • SMS-PIN completion — verifySmsTransfer(txnId, pin) / verifySmsSend(...) when initiate returned verificationMethod: "sms" . • Claim by code — claimTransfer(input) / claimCurrency(input) (a 200 with needsAccountSelection + candidates means re-submit with the chosen id). • Status polls — getTransferStatus(txnId) / getSendStatus(txnId) ( verificationState ), and getGuardianApprovalStatus(txnId) for guardian holds. • Phone-share — on a 409 PHONE_SHARE_APPROVAL_REQUIRED , run phoneShareInitiate → phoneShareApprove → phoneShareStatus , then re-issue the original request. • Server destinations — server.getDestinations({ sourceGameId, direction }) (game-secret) mirrors the browser call. Passkeys (WebAuthn) Passkeys replace the SMS PIN for approving sends/transfers on the web. The browser SDK wraps navigator.credentials , base64url encoding, challenge round-trips, and error mapping. client.ts await invo.enrollPasskey(); // once per user // Interchangeable methods: prove an existing method (e.g. the Invo app device key) // to authorize adding this passkey, then enroll. await invo.linkDevice(linkId); // → { status: "authorized" } await invo.enrollPasskey(); // First-enrollment OTP grant (v0.6.0+) — some tenants require it: try { await invo.enrollPasskey(); } catch (e) { if (e.isEnrollmentAuthorizationRequired) { // 6-digit code to phone + email await invo.enrollmentBegin(); await invo.enrollmentVerify(codeFromUser); await invo.enrollPasskey(); // retry — grant auto-consumed } else if (e.isEnrollmentProofRequired) { await invo.linkDevice(linkId); await invo.enrollPasskey(); } else throw e; } Prerequisite: Invo sets your tenant's WebAuthn RP ID + allowed origins . You must serve your integration from one of those origins or passkeys won't validate. See Platform Step-Up (WebAuthn) . Webhooks — grant value here Synchronous responses are for UX; reconcile and grant value off webhooks . They're HMAC-signed — verify X-Invo-Signature and dedupe on X-Invo-Idempotency-Key . Delivery is at-least-once, so keep your handler idempotent. server.ts — verify with the SDK (v0.3.0+) import { verifyWebhook, InvoError } from "@invonetwork/web-sdk/server"; // Pass the RAW request bytes + the X-Invo-Signature header. let event; try { event = verifyWebhook(rawBody, signatureHeader, process.env.INVO_WEBHOOK_SECRET); } catch (e) { return respond(400); // InvoError: WEBHOOK_SIGNATURE_INVALID | WEBHOOK_TIMESTAMP_EXPIRED | WEBHOOK_MALFORMED } // De-dupe yourself on X-Invo-Idempotency-Key, then handle: switch (event.event_type) { case "purchase.completed": grantCurrency(event.data); break; // event.data is typed case "item.purchased": grantItem(event.data); break; } verifyWebhook does the constant-time HMAC-SHA256 check, enforces a 5-minute replay window, and accepts an array of secrets during rotation ( verifyWebhook(body, sig, [oldSecret, newSecret]) ), returning a typed InvoWebhookEvent . The SDK verifies; you de-dupe on X-Invo-Idempotency-Key . Edge / serverless (v0.4.0+). verifyWebhook uses node:crypto ; on Cloudflare Workers, Deno, Vercel/Netlify Edge, or Bun use verifyWebhookAsync (Web Crypto) — same args, just await it — or the ready-made handler createWebhookHandler({ secret, onEvent }) , which returns a Fetch-API (Request) => Promise<Response> (Next.js App Router, Workers, Deno, Hono, Bun). Subscribe to every event with subscribed_events: ["*"] and filter server-side — new event types then reach you automatically. If you subscribe to a subset, you must include transfer.claim_pending (it's how you learn an inbound send/transfer is waiting to be collected — the most common integration gap). Event Fires when purchase.completed A currency or item purchase cleared and the player was credited (every rail). purchase.failed A card purchase attempt failed — declined, abandoned 3-D Secure, or cancelled. purchase.refunded A purchase was refunded (full or partial); the balance was debited. purchase.disputed A card chargeback / dispute changed state (carries a dispute_status field). purchase.fraud_warning A pre-dispute fraud warning was raised on a card charge. item.purchased A player spent game currency on one of your in-game items. transfer.sent A send / transfer was initiated from a player. transfer.received A send / transfer was credited to the destination player. transfer.claim_pending An inbound send/transfer is awaiting your player’s claim — drives the "you have X to collect" notice. transfer.claim_expired An unclaimed send / transfer expired. transfer.refunded An expired / unclaimed transfer was refunded to the sender. payout.status_changed A partner payout moved to a new lifecycle state. webhook.test A test event you triggered from the console. Reserved (schema-defined, not currently emitted): purchase.dispute_lost , balance.updated — their effects surface through the purchase.* / transfer.* events above. How SDK calls map to events: createCheckout / purchaseCurrency → purchase.* · purchaseItem → item.purchased · initiateSend / initiateTransfer → transfer.* . Full payloads, signature verification, retries & secret rotation: Receiving Webhooks . Resilience & observability (v0.3.0+) Automatic retries on network errors, 429 (honoring retry_after ), and 5xx with exponential backoff. Configure maxRetries (default 2, 0 disables) and retryBaseDelayMs . Only idempotent requests retry — single-use passkey POSTs never do. Observability hooks — onRequest / onResponse / onError (best-effort; a throwing hook never breaks a request). InvoError.requestId carries the backend request id for support tickets. Cancellation (v0.4.0+) — every method takes an optional final { signal } ( AbortSignal ); an aborted call throws InvoError code ABORTED and is never retried. config const invo = new InvoServer({ gameSecret: process.env.INVO_GAME_SECRET, baseUrl: "https://sandbox.invo.network/sandbox", maxRetries: 2, // default; 0 disables hooks: { onResponse: ({ status, durationMs, requestId }) => metrics(status, durationMs), onError: ({ error, willRetry }) => log(error.code, error.requestId, willRetry), }, }); Errors Every failure throws a typed InvoError with .code (when present), .status , .message , and .body , plus helpers: Helper Meaning .isTokenExpired Player token expired — re-mint + retry (automatic with refreshToken ) .isReceiverNotEnrolled Recipient has no passkey — fall back to claim-code entry .isInsufficientBalance Item purchase 400 — required_amount + current_balance on .body .isDuplicateRequest Idempotency-keyed request was a duplicate (409) .retryAfter Seconds to back off on a 429 throttle .requestId Backend request id (from the response headers) — quote it in support tickets Resources npm — @invonetwork/web-sdk GitHub — Invo-Technologies/invo-web-sdk Quick Start · Authentication · Sandbox Testing

---

## Python SDK

URL: https://docs.invo.network/docs/python-sdk

Official Invo Python server SDK. Install invonetwork to add currency purchase, item purchase, sends/transfers, balances, and webhook verification to any Python backend (Django, Flask, FastAPI).

Python SDK (server) invonetwork is the official first-party server-side SDK for integrating Invo from a Python backend (Django, Flask, FastAPI, or plain Python). It's the Python counterpart to the Web / TypeScript SDK — same endpoints, field names, and webhook signing scheme, so both stay in lockstep. Server-side only — holds your game secret This SDK authenticates with your game secret and is meant for your backend. For the browser half (passkey enroll/approve, self-claim, balances/destinations for a logged-in player), pair it with the Web SDK — the game secret never reaches the browser. Not in this SDK (by design): the player-token WebAuthn ceremonies — passkey enroll, approve/step-up, confirm-receipt/claim, the enrollment OTP grant, and device link. Those run in the browser ( navigator.credentials ) via the Web SDK 's InvoClient , or you relay them through your backend. Everything game-secret (mint, initiate, verify-SMS, claim, status, guardian, phone-share, checkout, purchase, item purchase, balances, inbound-pending, destinations, linked-identities, webhook verification) is here. Install and call in minutes pip install invonetwork — Python 3.9+, zero runtime dependencies. View on PyPI and GitHub . Currency & Item Purchase Hosted checkout, direct rail, and spend-currency item purchases Sends & Transfers Initiate on the server; the browser approves by passkey Balances & Reads Player balances, inbound-pending, linked identities, order details Webhook Verification Constant-time HMAC verification with typed events Install Requires Python 3.9+ . The exact command differs slightly by OS — use the one for your platform: macOS / Linux Terminal (macOS / Linux) python3 -m pip install invonetwork Windows PowerShell (Windows) py -m pip install invonetwork Recommended: inside a virtual environment macOS / Linux python3 -m venv .venv source .venv/bin/activate pip install invonetwork Windows (PowerShell) py -m venv .venv .venv\Scripts\Activate.ps1 pip install invonetwork Full stack? Install the server SDK here and the browser SDK on your web front-end: The two SDKs # Python backend (this package) pip install invonetwork # Web / browser front-end (Node ≥ 18) npm install @invonetwork/web-sdk Quickstart Construct one InvoServer with your game secret and reuse it. Get your secret and base URLs from the Invo console ( https://console.invo.network for production, https://dev.console.invo.network for testing). server.py from invonetwork import InvoServer invo = InvoServer( game_secret="sk_live_...", # server-side ONLY base_url="https://sandbox.invo.network/sandbox", # prod: https://invo.network ) # Mint a short-lived, game-scoped token for the browser SDK to use token = invo.mint_player_token(player_email="player@example.com") # Spend game currency on an in-game item (balance debit; grant off the item.purchased webhook) order = invo.purchase_item( client_request_id="req-123", # idempotency key player_email="player@example.com", player_name="Ada", item_id="sword_001", item_name="Flaming Sword", item_quantity=1, unit_price="150.00", total_price="150.00", ) # Read a player's balances balance = invo.get_player_balance(player_email="player@example.com") Verify webhooks Pass the raw request bytes (never a re-serialized object) and your signing secret. verify_webhook checks the HMAC in constant time, rejects stale timestamps, supports secret rotation, and returns a typed event. Flask from flask import Flask, request from invonetwork import verify_webhook, InvoError app = Flask(__name__) @app.post("/invo/webhooks") def invo_webhook(): try: event = verify_webhook( request.get_data(), # RAW bytes request.headers.get("X-Invo-Signature"), "whsec_...", # your signing secret (or a list during rotation) ) except InvoError: return "", 400 # bad signature / stale / malformed if event.event_type == "purchase.completed": grant_currency(event.data) # idempotent on event.idempotency_key return "", 200 FastAPI from fastapi import FastAPI, Request, Response from invonetwork import verify_webhook, InvoError app = FastAPI() @app.post("/invo/webhooks") async def invo_webhook(request: Request): raw = await request.body() try: event = verify_webhook(raw, request.headers.get("X-Invo-Signature"), "whsec_...") except InvoError: return Response(status_code=400) # handle event.event_type ... return Response(status_code=200) Inbound "to collect" (incoming from other games) get_inbound_pending lists a player's incoming, unclaimed sends/transfers — including value sent from other games to a player on your platform. It's the source of truth behind a "you have X to collect" badge, and pairs with the transfer.claim_pending webhook. inbound to collect pending = server.get_inbound_pending(player_email="p@example.com") # or player_phone=... for row in pending.inbound_pending: # row.source_game = where it came from (another game). Match row.to_phone to the player; # row.to_identity_id is None when the phone maps to >1 of your players (don't require it). print(row.transaction_id, row.net_amount, row.to_phone, row.source_game) # Lists only pending/unclaimed; a claimed transfer drops off. This is the server/platform view (game-secret). The browser player-token equivalent is the JS SDK's client.getPendingCollect() , where incoming rows come back as kind="receiving_confirm" — render those, not just player-initiated ones. Errors Every failure raises InvoError with .code , .status , .message , .body , and .request_id , plus classifier helpers so you don't string-match: error handling from invonetwork import InvoError try: invo.purchase_item(...) except InvoError as e: if e.is_insufficient_balance: ... # not enough currency elif e.is_duplicate_request: ... # replayed client_request_id elif e.retry_after is not None: ... # throttled; back off e.retry_after seconds else: raise What's included Tokens & flows: mint_player_token , initiate_send , initiate_transfer , create_checkout , purchase_currency , confirm_payment , purchase_item Completion & recovery (v0.2.0+): verify_sms_transfer / verify_sms_send , claim_transfer / claim_currency , get_transfer_status / get_send_status , get_guardian_approval_status Phone-share & destinations (v0.3.0+): phone_share_initiate / phone_share_approve / phone_share_status (resolve a 409 PHONE_SHARE_APPROVAL_REQUIRED ), and server-side get_destinations(source_game_id=..., direction=...) Reads: get_order_details , get_item_purchase_history (+ iterate_item_purchase_history ), get_item_order_details , get_player_balance , get_inbound_pending , get_linked_identities Webhooks: verify_webhook with a typed WebhookEvent Resilience: automatic retries (network / 429 / 5xx, idempotent-only, honoring retry_after ), timeouts, and observability hooks Types: full type hints, ships py.typed ( mypy --strict clean)

---

## Game Registration

URL: https://docs.invo.network/docs/game-registration

Step-by-step guide to register your game with Invo Network and get API credentials for cross-game currency integration.

Game Registration Register your game with the INVO Network platform through our comprehensive 4-step game wizard. Get your auto-generated SDK key, configure your currency, and start integrating immediately. Game Assets & Info Upload your game icon, cover image, and configure basic game information and transfer policies. Auto-Generated SDK Key Receive your unique SDK key automatically generated in step 2 with format ivsdk_[64-chars]. Default Currency Setup Configure your primary currency with symbol, transfer limits, and exchange rules. Payout Integration Optional Plaid bank integration for automated revenue payouts and financial management. Immediate Access Start using your SDK key immediately after wizard completion - no approval delays. Production Ready Your game is instantly live on the INVO Network with full currency operation capabilities. 4-Step Game Registration Wizard Complete your game setup through our streamlined wizard at console.invo.network : 1 Game Information & Assets Upload assets and configure your game's basic information and transfer settings. Required Assets: • Game icon (square format) • Cover image (1920x1080px) Game Details: • Game name & developer • Genre(s) & platform(s) • Transfer policy (Universal/Manual) 2 SDK Key Generation Your unique API key is automatically generated for immediate use. Auto-Generated Format: ivsdk_[64-character-random-string] Usage: Include in X-Game-Secret-Key: {SDK_KEY} header on every API request Security: Server-side only, never expose in client code 3 Default Currency Setup Configure your game's primary currency with transfer rules and limits. Currency Config: • Currency name & symbol • Symbol image URL (optional) • Starting player amount Transfer Rules: • Transferable (yes/no) • Minimum transfer amount • Maximum transfer amount 4 Payout Setup (Optional) Connect your bank account via Plaid for automated revenue payouts. Bank Integration: Secure Plaid connection for ACH transfers Revenue Sources: Transfer fees (3.5%) + Item sales profit (95%) Alternative: Manual check payments if Plaid not available Game Configuration Example Here's an example of the data structure created during your game registration: Complete Game Registration Data // Step 1: Game Information { "gameName": "Epic Adventure RPG", "developerName": "Your Studio Name", "publisherName": "Your Publisher", "gameDescription": "A fantasy RPG with cross-platform progression", "genre": ["RPG", "Adventure"], "platform": ["PC", "Mobile", "Console"], "gameUrl": "https://epicadventure.game", "gameIconUrl": "https://storage.googleapis.com/your-bucket/game-icon.png", "coverImageUrl": "https://storage.googleapis.com/your-bucket/cover.jpg", "universalTransfers": "yes", // or "no" for manual linking "linkedGameIds": [], // populated if universalTransfers = "no" "paymentRail": "game" // platform | game | steam — see "Payment route" below (default: platform) } // Step 2: Auto-Generated SDK Key { "sdkKey": "your_secret_key" } // Step 3: Default Currency { "defaultCurrency": { "currency_name": "Gold Coins", "currency_symbol": "GC", "currency_symbol_url": "https://storage.googleapis.com/your-bucket/coin.png", "currency_amount": 1000, // Starting amount for new players "currency_type": "default currency", "transferable": true, "minimum_transfer_amount": 10, "maximum_transfer_amount": 10000 } } // Step 4: Payout Configuration (Optional) { "payoutMethod": "bank", // or "mail" "bankDetails": { "accountHolderName": "Your Studio Name", "bankName": "Chase Bank", "routingNumber": "021000021", "accountNumber": "1234567890", // Only last 4 digits stored "accountType": "business_checking" } } Payment route Set paymentRail at registration so your purchases route correctly — you pick by where your product lives, and never deal with a payment processor directly: platform — a platform or non-game app (web/mobile storefront, creator platform). Default. game — a game distributed anywhere except Steam (mobile, standalone, web, console store). steam — a game distributed on Steam (players pay with their Steam Wallet). Set it once here and every purchase for this game routes automatically — no need to pass a rail on each call. You can change it later if your distribution changes. See Payment Methods for the full guide. Immediate API Access Your SDK key is active immediately after wizard completion. Start integrating right away: Production Environment Base URL: invo.network/api SDK Key: ivsdk_your_key... Status: Live Immediately First API Call Test API Access // Test your SDK key immediately const response = await fetch( 'https://invo.network/api/player-balances/player/by-email/test@example.com', { headers: { 'X-Game-Secret-Key': YOUR_SDK_KEY } } ); // 404 here is expected if the player doesn't exist yet — players auto-create // the first time they hit a writing endpoint (purchase-currency, purchase-item). console.log(response.status, await response.json()); Game Status Options During registration, you can set your game's initial status: 🔧 Testing Status • For games in development • Full API access available • Can change to Live anytime • Default status for new games 🚀 Live Status • For launched games • Full production capabilities • Real money transactions enabled • Revenue sharing active Prerequisites Before registering your game, ensure you have: • Completed developer account registration at console.invo.network • Game assets ready (square icon, 1920x1080 cover image) • Decided on currency name, symbol, and transfer policy • Bank account information if enabling payouts • Server-side integration capability (SDK keys are server-only) • Understanding of your game's monetization and currency flow Transfer Policy Options In Step 1, choose how your game participates in cross-game transfers: 🌍 Universal Transfers • Accept transfers from any INVO game • Send transfers to any INVO game • Maximum network reach • Recommended for most games 🎯 Manual Linking • Only transfer with specific games • Choose your partner games • More controlled ecosystem • Good for game series/franchises Post-Registration Benefits After completing the 4-step wizard, you immediately gain: • Instant SDK Key: Ready-to-use API authentication • Full API Access: Player balances, transfers, purchases, item sales • Developer Dashboard: Analytics, revenue tracking, game management • Email Confirmation: SDK key sent to your email with integration instructions • Currency Operations: Accept purchases, track balances, process transfers • Revenue Sharing: Earn from transfer fees (3.5%) and item sales (95%) • Network Access: Connect with thousands of registered INVO games

---

## Player Management

URL: https://docs.invo.network/docs/player-management

Manage players in your game using Invo Network API. Create, update, and track player accounts across games.

Player Management API Essential player balance management APIs designed for games with 60M+ players. Optimized for high-volume operations with intelligent caching, circuit breakers, and streaming capabilities for massive scale. Individual Player Lookup Get player balance by email with 5-minute caching and 200/minute rate limits for high-volume games. Batch Operations Process up to 100K players per request with memory-efficient chunked processing and optimized queries. Full Player Streaming Stream all players for data exports and analytics with configurable chunk sizes up to 50K per chunk. Game-Wide Analytics Real-time game statistics including player counts, balance totals, and recent activity with SQL optimization. Circuit Breaker Protection Built-in protection against database overload with automatic failover and degraded service modes. Cache Invalidation Real-time cache invalidation webhooks to keep player data fresh across all balance changes. Individual Player Lookup The most common operation - get player balance by email. Optimized for 60M+ player games with aggressive caching. 📈 Performance Specs • Rate Limit: 2000/minute per game • Cache TTL: 5 minutes for individual lookups • Response Time: ~50ms (cached), ~200ms (DB) • Circuit Breaker: 5 failures, 30s reset 🔍 Use Cases • Player login balance display • Purchase eligibility checks • Real-time balance updates • Customer support lookups Individual Player Balance Lookup // GET /api/player-balances/player/by-email/{email} const SDK_KEY = 'ivsdk_your_64_character_key_here'; async function getPlayerBalance(playerEmail) { const response = await fetch( `https://invo.network/api/player-balances/player/by-email/${encodeURIComponent(playerEmail)}`, { method: 'GET', headers: { 'X-Game-Secret-Key': SDK_KEY, 'Content-Type': 'application/json' } } ); if (response.ok) { return await response.json(); } else { throw new Error(`API Error: ${response.status}`); } } // Example usage try { const playerData = await getPlayerBalance('player@example.com'); console.log('Player Balance:', playerData); // Response structure: // { // "player": { // "player_id": 12345, // "player_name": "PlayerOne", // "player_email": "player@example.com", // "date_joined": "2024-01-15T10:30:00Z" // }, // "balances": [ // { // "currency_id": 1, // "currency_name": "Gold Coins", // "available_balance": "1500.00", // "reserved_balance": "50.00", // "total_balance": "1550.00" // } // ], // "summary": { // "total_value": "1550.00", // "currency_count": 1, // "has_funds": true // }, // "last_updated": "2024-12-09T15:30:45Z" // } } catch (error) { console.error('Failed to get player balance:', error); } Batch Player Operations Process up to 100K players per request with memory-efficient chunked processing. Essential for analytics and bulk operations. 100K Max Players per Batch 5K Chunk Size for Processing 50/min Rate Limit per Game Batch Player Balance Operations // POST /api/player-balances/batch async function getBatchPlayerBalances(playerEmails = [], playerIds = []) { const totalRequested = playerEmails.length + playerIds.length; if (totalRequested > 100000) { throw new Error('Batch too large. Maximum 100,000 players per request.'); } const response = await fetch('https://invo.network/api/player-balances/batch', { method: 'POST', headers: { 'X-Game-Secret-Key': SDK_KEY, 'Content-Type': 'application/json' }, body: JSON.stringify({ player_emails: playerEmails, player_ids: playerIds }) }); return await response.json(); } // Example: Batch lookup for analytics const guildMemberEmails = [ 'leader@guild.com', 'member1@guild.com', 'member2@guild.com', // ... up to 100K emails ]; try { const batchResult = await getBatchPlayerBalances(guildMemberEmails); console.log(`Found ${batchResult.summary.total_found} of ${batchResult.summary.total_requested} players`); // Process results batchResult.results.forEach(result => { if (result.error) { console.log(`Player not found: ${result.player.player_email}`); } else { console.log(`${result.player.player_name}: ${result.total_value} total value`); } }); // Response structure: // { // "results": [ // { // "player": { // "player_id": 12345, // "player_email": "leader@guild.com", // "player_name": "GuildLeader" // }, // "balances": [...], // "total_value": "5000.00" // }, // { // "player": {"player_email": "notfound@guild.com"}, // "error": "Player not found", // "balances": [] // } // ], // "summary": { // "total_requested": 3, // "total_found": 2, // "total_not_found": 1 // }, // "retrieved_at": "2024-12-09T15:30:45Z" // } } catch (error) { console.error('Batch request failed:', error); } Full Player Data Streaming Stream ALL players for games with 60M+ players. Essential for data exports, analytics, and full game backups. ⚡ Streaming Features Performance • Up to 50K players per chunk • Memory-efficient processing • Progress logging every 10K players • Automatic session cleanup Controls • Resume from specific player ID • Include/exclude zero balances • Rate limited: 5/hour per game • Real-time JSON streaming Full Player Data Streaming // GET /api/player-balances/stream-all async function streamAllPlayers(options = {}) { const params = new URLSearchParams({ last_player_id: options.lastPlayerId || 0, chunk_size: Math.min(options.chunkSize || 10000, 50000), include_zero_balances: options.includeZeroBalances || false }); const response = await fetch( `https://invo.network/api/player-balances/stream-all?${params}`, { method: 'GET', headers: { 'X-Game-Secret-Key': SDK_KEY, 'Content-Type': 'application/json' } } ); if (!response.ok) { throw new Error(`Stream failed: ${response.status}`); } // Handle streaming response const reader = response.body.getReader(); const decoder = new TextDecoder(); let buffer = ''; try { while (true) { const { done, value } = await reader.read(); if (done) break; buffer += decoder.decode(value, { stream: true }); // Process complete JSON objects as they arrive const lines = buffer.split('\n'); buffer = lines.pop(); // Keep incomplete line in buffer for (const line of lines) { if (line.trim()) { try { const data = JSON.parse(line); console.log('Received player chunk:', data); } catch (e) { // Ignore parsing errors for partial data } } } } } finally { reader.releaseLock(); } } // Example: Stream with progress tracking let totalProcessed = 0; let lastPlayerId = 0; async function exportAllPlayers() { const batchSize = 25000; // 25K players per chunk console.log('Starting full player export...'); try { await streamAllPlayers({ lastPlayerId: lastPlayerId, chunkSize: batchSize, includeZeroBalances: false // Only players with funds }); console.log(`Export completed. Total processed: ${totalProcessed}`); } catch (error) { console.error('Export failed:', error); console.log(`Resume from player ID: ${lastPlayerId}`); } } // Stream response format: // { // "status": "streaming", // "data": [ // { // "player_id": 12345, // "player_email": "player@example.com", // "player_name": "PlayerName", // "balances": [ // { // "currency_id": 1, // "currency_name": "Gold Coins", // "available": "1500.00", // "total": "1550.00" // } // ], // "total_value": "1550.00" // } // ], // "total_streamed": 25000, // "last_player_id": 67890 // } Game-Wide Analytics Get essential game statistics optimized for 60M+ player games with SQL-optimized queries and 10-minute caching. Game-Wide Analytics & Statistics // GET /api/player-balances/game-summary async function getGameSummary() { const response = await fetch('https://invo.network/api/player-balances/game-summary', { method: 'GET', headers: { 'X-Game-Secret-Key': SDK_KEY, 'Content-Type': 'application/json' } }); return await response.json(); } // Example usage for dashboard try { const summary = await getGameSummary(); console.log('Game Analytics:'); console.log(`Total Players: ${summary.players.total_players.toLocaleString()}`); console.log(`New Players (24h): ${summary.players.new_players_24h}`); console.log(`Transactions (24h): ${summary.activity.transactions_24h}`); // Economy breakdown by currency summary.economy.forEach(currency => { console.log(`\n${currency.currency_name}:`); console.log(` Funded Players: ${currency.funded_players.toLocaleString()}`); console.log(` Total Balance: ${currency.total_balance}`); console.log(` Average Balance: ${currency.average_balance}`); }); // Response structure: // { // "players": { // "total_players": 62500000, // "new_players_24h": 125000 // }, // "economy": [ // { // "currency_name": "Gold Coins", // "funded_players": 45000000, // "total_balance": "2500000000.00", // "average_balance": "55.56" // }, // { // "currency_name": "Premium Gems", // "funded_players": 15000000, // "total_balance": "500000000.00", // "average_balance": "33.33" // } // ], // "activity": { // "transactions_24h": 850000 // }, // "generated_at": "2024-12-09T15:30:45Z" // } } catch (error) { console.error('Failed to get game summary:', error); } Real-Time Cache Management Keep player data fresh with webhook-based cache invalidation. Call after every balance change to maintain data consistency. ⚡ Cache Strategy • Individual lookups: 5-minute TTL • Batch requests: 1-minute TTL • Game summary: 10-minute TTL • Webhook invalidation: Immediate 🔄 Invalidation Events • Currency purchases completed • Transfer transactions processed • Item purchases made • Manual balance adjustments Cache Invalidation Webhooks // POST /api/player-balances/webhook/balance-updated async function invalidatePlayerCache(gameId, playerId, playerEmail = null) { const response = await fetch('https://invo.network/api/player-balances/webhook/balance-updated', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ game_id: gameId, player_id: playerId, player_email: playerEmail }) }); return await response.json(); } // Example: Invalidate cache after currency purchase async function processCurrencyPurchase(playerId, amount) { try { // 1. Process the purchase (your existing logic) const purchase = await completePurchaseTransaction(playerId, amount); // 2. Invalidate cache immediately await invalidatePlayerCache( purchase.game_id, purchase.player_id, purchase.player_email ); console.log('Purchase completed and cache invalidated'); return purchase; } catch (error) { console.error('Purchase or cache invalidation failed:', error); throw error; } } // Example: Batch cache invalidation after transfers async function invalidateBatchTransferCaches(transferResults) { const invalidationPromises = transferResults.map(result => { if (result.success) { return Promise.all([ // Invalidate sender cache invalidatePlayerCache(result.from_game_id, result.from_player_id, result.from_player_email), // Invalidate receiver cache invalidatePlayerCache(result.to_game_id, result.to_player_id, result.to_player_email) ]); } }); await Promise.all(invalidationPromises); console.log('All transfer caches invalidated'); } Error Handling & Circuit Breakers Robust error handling with circuit breaker protection to prevent cascade failures in high-volume games. 🔒 Circuit Breaker • Fail threshold: 5 errors • Reset timeout: 30 seconds • Excludes: ValueError, KeyError • State: Open/Closed/Half-Open ⚠️ Rate Limiting • Individual: 2000/min per game • Batch: 50/min per game • Streaming: 5/hour per game • Webhooks: 10K/min global 🏥 Health Monitoring • Database connectivity • Cache availability • Circuit breaker status • Service degradation alerts Robust Error Handling & Retry Logic // Comprehensive error handling for player management class PlayerAPIClient { constructor(sdkKey) { this.sdkKey = sdkKey; this.baseURL = 'https://invo.network/api/player-balances'; } async request(endpoint, options = {}) { const response = await fetch(`${this.baseURL}${endpoint}`, { ...options, headers: { 'X-Game-Secret-Key': this.sdkKey, 'Content-Type': 'application/json', ...options.headers } }); // Handle specific error cases switch (response.status) { case 200: return await response.json(); case 404: throw new PlayerNotFoundError('Player not found'); case 429: const retryAfter = response.headers.get('Retry-After') || 60; throw new RateLimitError(`Rate limit exceeded. Retry after ${retryAfter} seconds`); case 503: const errorData = await response.json(); if (errorData.error === 'service_unavailable') { throw new CircuitBreakerError('Service temporarily unavailable due to circuit breaker'); } throw new ServiceError('Service unavailable'); case 401: throw new AuthenticationError('Invalid SDK key'); case 400: const badRequestData = await response.json(); throw new ValidationError(badRequestData.message); default: throw new APIError(`API request failed with status ${response.status}`); } } async getPlayerBalanceWithRetry(playerEmail, maxRetries = 3) { for (let attempt = 1; attempt <= maxRetries; attempt++) { try { return await this.request(`/player/by-email/${encodeURIComponent(playerEmail)}`); } catch (error) { if (error instanceof CircuitBreakerError && attempt < maxRetries) { // Wait before retry for circuit breaker await new Promise(resolve => setTimeout(resolve, 30000)); continue; } if (error instanceof RateLimitError && attempt < maxRetries) { // Exponential backoff for rate limits const delay = Math.pow(2, attempt) * 1000; await new Promise(resolve => setTimeout(resolve, delay)); continue; } throw error; // Re-throw if max retries exceeded } } } } // Custom error classes class PlayerNotFoundError extends Error {} class RateLimitError extends Error {} class CircuitBreakerError extends Error {} class AuthenticationError extends Error {} class ValidationError extends Error {} class ServiceError extends Error {} class APIError extends Error {} // Usage with error handling const client = new PlayerAPIClient('ivsdk_your_key_here'); try { const playerData = await client.getPlayerBalanceWithRetry('player@example.com'); console.log('Player data retrieved successfully:', playerData); } catch (error) { if (error instanceof PlayerNotFoundError) { console.log('Player not found - might be a new user'); } else if (error instanceof RateLimitError) { console.log('Rate limited - implementing backoff'); } else if (error instanceof CircuitBreakerError) { console.log('Service degraded - using cached data or fallback'); } else { console.error('Unexpected error:', error.message); } } Performance Optimization Tips Best practices for optimal performance when managing millions of players. ⚡ Query Optimization • Cache First: Always check cache before API calls • Batch Wisely: Use batch endpoint for 100+ players • Stream Large Exports: Use streaming for full data exports • Invalidate Immediately: Clear cache after balance changes 🎯 Integration Patterns • Server-Side Only: Never call from client code • Connection Pooling: Reuse HTTP connections • Async Processing: Use Promise.all for parallel requests • Circuit Breaker Aware: Handle degraded service gracefully Service Health Monitoring Monitor API health and performance with built-in health check endpoints. Rate Limits & Usage Guidelines Essential limits to ensure optimal performance for all games on the network: Per-Game Limits • Individual Lookups: 2,000/minute • Batch Requests: 50/minute • Game Summary: 100/minute • Full Streaming: 5/hour Best Practices • Cache responses for 5+ minutes when possible • Use batch endpoint for 100+ concurrent lookups • Implement exponential backoff for rate limit errors • Monitor circuit breaker state for service health Real-World Integration Examples Common integration patterns for different game scenarios and player volumes. 🏰 Guild Management System Guild Raid Eligibility Checker // Guild balance checking for raid eligibility class GuildManager { constructor(sdkKey) { this.apiClient = new PlayerAPIClient(sdkKey); } async checkRaidEligibility(guildMembers, minimumBalance = 1000) { // Use batch API for guild member lookup const memberEmails = guildMembers.map(member => member.email); try { const batchResult = await this.apiClient.request('/batch', { method: 'POST', body: JSON.stringify({ player_emails: memberEmails }) }); const eligibleMembers = []; const ineligibleMembers = []; batchResult.results.forEach(result => { if (result.error) { ineligibleMembers.push({ email: result.player.player_email, reason: 'Player not found' }); return; } const totalValue = parseFloat(result.total_value); if (totalValue >= minimumBalance) { eligibleMembers.push({ ...result.player, totalValue }); } else { ineligibleMembers.push({ ...result.player, totalValue, reason: `Insufficient funds (needs ${minimumBalance}, has ${totalValue})` }); } }); return { eligible: eligibleMembers, ineligible: ineligibleMembers, eligibilityRate: (eligibleMembers.length / memberEmails.length) * 100 }; } catch (error) { console.error('Guild eligibility check failed:', error); throw error; } } } 🏆 Leaderboard Generation Wealth Leaderboard from 60M+ Players // Generate wealth leaderboards from streaming data class LeaderboardGenerator { constructor(sdkKey) { this.apiClient = new PlayerAPIClient(sdkKey); } async generateWealthLeaderboard(topN = 100) { const leaderboard = []; let processedCount = 0; console.log('Starting wealth leaderboard generation...'); try { // Stream all players and track top performers const response = await fetch('https://invo.network/api/player-balances/stream-all?include_zero_balances=false', { headers: { 'X-Game-Secret-Key': this.apiClient.sdkKey } }); const reader = response.body.getReader(); const decoder = new TextDecoder(); while (true) { const { done, value } = await reader.read(); if (done) break; const chunk = decoder.decode(value); const players = this.parseStreamChunk(chunk); players.forEach(player => { const totalValue = parseFloat(player.total_value); if (totalValue > 0) { leaderboard.push({ playerId: player.player_id, playerName: player.player_name, totalValue: totalValue }); // Keep only top N + buffer for efficiency if (leaderboard.length > topN * 2) { leaderboard.sort((a, b) => b.totalValue - a.totalValue); leaderboard.splice(topN); } } processedCount++; if (processedCount % 50000 === 0) { console.log(`Processed ${processedCount.toLocaleString()} players...`); } }); } // Final sort and trim leaderboard.sort((a, b) => b.totalValue - a.totalValue); const finalLeaderboard = leaderboard.slice(0, topN).map((player, index) => ({ rank: index + 1, ...player })); console.log(`Leaderboard generated from ${processedCount.toLocaleString()} players`); return finalLeaderboard; } catch (error) { console.error('Leaderboard generation failed:', error); throw error; } } parseStreamChunk(chunk) { // Parse streaming JSON data (simplified) try { return JSON.parse(chunk).data || []; } catch { return []; } } } 🎧 Customer Support Tools Customer Support Player Lookup // Customer support player lookup with comprehensive info class CustomerSupportAPI { constructor(sdkKey) { this.apiClient = new PlayerAPIClient(sdkKey); } async getPlayerSupportInfo(playerEmail) { try { // Get current balance const balanceData = await this.apiClient.request( `/player/by-email/${encodeURIComponent(playerEmail)}` ); if (!balanceData.player) { return { found: false, message: 'Player not found in system' }; } // Get game-wide context for comparison const gameSummary = await this.apiClient.request('/game-summary'); // Calculate player percentiles const playerTotalValue = parseFloat(balanceData.summary.total_value); const avgBalance = parseFloat(gameSummary.economy[0]?.average_balance || 0); return { found: true, player: { ...balanceData.player, accountAge: this.calculateAccountAge(balanceData.player.date_joined), balances: balanceData.balances, totalValue: playerTotalValue, comparedToAverage: playerTotalValue / avgBalance, hasActiveBalances: balanceData.summary.has_funds, currencyCount: balanceData.summary.currency_count }, gameContext: { totalPlayers: gameSummary.players.total_players, averageBalance: avgBalance, newPlayersToday: gameSummary.players.new_players_24h }, supportNotes: this.generateSupportNotes(balanceData, gameSummary) }; } catch (error) { if (error instanceof PlayerNotFoundError) { return { found: false, message: 'Player not found' }; } throw error; } } calculateAccountAge(dateJoined) { if (!dateJoined) return 'Unknown'; const joinDate = new Date(dateJoined); const now = new Date(); const diffMs = now - joinDate; const diffDays = Math.floor(diffMs / (1000 * 60 * 60 * 24)); if (diffDays < 1) return 'Less than 1 day'; if (diffDays < 30) return `${diffDays} days`; if (diffDays < 365) return `${Math.floor(diffDays / 30)} months`; return `${Math.floor(diffDays / 365)} years`; } generateSupportNotes(balanceData, gameSummary) { const notes = []; const totalValue = parseFloat(balanceData.summary.total_value); const avgBalance = parseFloat(gameSummary.economy[0]?.average_balance || 0); if (totalValue === 0) { notes.push('⚠️ Player has zero balance across all currencies'); } else if (totalValue > avgBalance * 10) { notes.push('💎 High-value player (10x+ average balance)'); } else if (totalValue < avgBalance * 0.1) { notes.push('📊 Below-average balance (less than 10% of average)'); } if (balanceData.summary.currency_count > 1) { notes.push(`🪙 Uses ${balanceData.summary.currency_count} different currencies`); } return notes; } } Security & Best Practices Essential security practices for managing player data at scale: 🔐 Authentication & Security • Always use SDK key in X-Game-Secret-Key header on every request • Never expose SDK keys in client-side code or logs • Store SDK keys in secure environment variables • Use HTTPS for all API communications • Implement proper error handling to prevent data leaks ⚡ Performance & Reliability • Implement client-side caching with appropriate TTLs • Use batch endpoints for multiple player lookups • Handle rate limits with exponential backoff • Monitor circuit breaker status for service health • Invalidate cache immediately after balance changes

---

## Virtual Currency Setup

URL: https://docs.invo.network/docs/virtual-currency

Configure virtual currency in your game for cross-game transfers using Invo Network API.

Virtual Currency Setup Configure your game's virtual currencies through the INVO Network console at console.invo.network . Set up your default currency during game registration and manage additional currencies as your game grows. Default Currency Setup Configure your primary currency during game registration with name, symbol, and starting amounts. Transfer Configuration Set transfer rules including minimum/maximum amounts and transferability settings. Symbol Image Upload Upload custom currency symbols and icons with automatic Google Cloud Storage hosting. Currency Management Add, edit, and manage multiple currencies through the developer console interface. Player Starting Balances Configure how much currency new players receive when they first join your game. Cross-Game Compatibility Enable your currency for transfers across the entire INVO Network ecosystem. Default Currency Setup In Step 3 of the game registration wizard, you configure your primary currency that all new players will receive. 🪙 Currency Configuration Fields Basic Information • Currency Name: Display name for your currency (e.g., "Gold Coins") • Currency Symbol: Short abbreviation (e.g., "GC", "GOLD") • Currency Symbol URL: Optional image/icon for your currency • Starting Amount: How much new players receive initially Transfer Settings • Transferable: Allow players to send/receive this currency • Minimum Transfer: Smallest amount that can be transferred • Maximum Transfer: Largest amount that can be transferred • Currency Type: Automatically set to "default currency" Default Currency JSON Structure // Example default currency configuration from Step 3 { "currency_name": "Gold Coins", "currency_symbol": "GC", "currency_symbol_url": "https://storage.googleapis.com/your-bucket/gold-coin.png", "currency_amount": 1000, "currency_type": "default currency", "transferable": true, "minimum_transfer_amount": 10, "maximum_transfer_amount": 50000 } // This creates a currency where: // - New players start with 1,000 Gold Coins // - Players can transfer between 10-50,000 GC // - Currency is transferable across INVO Network // - Custom coin image hosted automatically Currency Symbol Upload Upload custom images for your currency symbols through the console interface. Images are automatically uploaded to Google Cloud Storage and optimized for display across the network. 📷 Image Requirements • Format: PNG, JPG, or SVG • Size: Recommended 64x64px or 128x128px • Background: Transparent PNG preferred • Max File Size: 2MB ☁️ Auto-Hosting • Uploaded to Google Cloud Storage • Globally distributed CDN • Automatic optimization • Permanent URL generation Upload Process 1 Select Image File Choose your currency symbol image from your computer 2 Automatic Upload Console uploads to Google Cloud Storage and generates permanent URL 3 URL Auto-Population The currency_symbol_url field is automatically filled with the hosted URL Transfer Configuration Configure how your currency can be transferred between players and across games in the INVO Network. 🔄 Transferable Currency When Enabled: • Players can send currency to other players • Currency can move between different INVO games • Enables cross-game ecosystem participation • Subject to minimum/maximum transfer limits When Disabled: • Currency stays within your game only • No player-to-player transfers • Isolated economy system • Can be enabled later if needed 💰 Transfer Limits Minimum Transfer Amount: • Prevents spam micro-transactions • Reduces network transaction costs • Typical range: 1-100 currency units • Can be adjusted after game launch Maximum Transfer Amount: • Prevents large unauthorized transfers • Reduces risk of account theft impact • Typical range: 1,000-100,000 units • Balance convenience vs security Transfer Configuration Examples // Transfer configuration examples // Conservative Setup (Secure) { "transferable": true, "minimum_transfer_amount": 50, "maximum_transfer_amount": 1000 } // Good for: New games, high-value currencies, security-focused // Moderate Setup (Balanced) { "transferable": true, "minimum_transfer_amount": 10, "maximum_transfer_amount": 10000 } // Good for: Most games, balanced convenience and security // Liberal Setup (Convenient) { "transferable": true, "minimum_transfer_amount": 1, "maximum_transfer_amount": 100000 } // Good for: Established games, low-value currencies, convenience-focused // Isolated Setup (Game-Only) { "transferable": false, "minimum_transfer_amount": 0, "maximum_transfer_amount": 0 } // Good for: Competitive games, unique economies, no cross-game transfers Currency Management Console Access the currency management interface at console.invo.network to add, edit, and manage multiple currencies for your game. Add Currency Create new currencies beyond your default Edit Settings Modify transfer limits and properties View Analytics Monitor currency usage and transfers Archive Currency Safely remove unused currencies Console Interface Features Currency List View • View all game currencies in one table • Sort by name, type, or creation date • Quick status indicators (active/inactive) • Bulk actions for multiple currencies Individual Currency Management • Edit transfer limits in real-time • Upload/change currency symbols • View transfer history and analytics • Configure player starting amounts Multiple Currency Setup Beyond your default currency, you can add premium currencies, seasonal currencies, or specialized tokens for different game mechanics. 💰 Premium Currency • Purchased with real money • Higher transfer limits • Special game features access • Example: "Premium Gems" 🎃 Seasonal Currency • Limited-time availability • Event-specific rewards • Non-transferable often • Example: "Halloween Tokens" 🏆 Achievement Currency • Earned through gameplay • Merit-based distribution • Special store access • Example: "Honor Points" Multi-Currency Game Setup // Multi-currency game configuration example { "game_currencies": [ { "currency_name": "Gold Coins", "currency_symbol": "GC", "currency_type": "default currency", "currency_amount": 1000, "transferable": true, "minimum_transfer_amount": 10, "maximum_transfer_amount": 50000 }, { "currency_name": "Premium Gems", "currency_symbol": "PG", "currency_type": "premium currency", "currency_amount": 100, "transferable": true, "minimum_transfer_amount": 1, "maximum_transfer_amount": 10000 }, { "currency_name": "Event Tokens", "currency_symbol": "ET", "currency_type": "seasonal currency", "currency_amount": 0, "transferable": false, "minimum_transfer_amount": 0, "maximum_transfer_amount": 0 }, { "currency_name": "Honor Points", "currency_symbol": "HP", "currency_type": "achievement currency", "currency_amount": 0, "transferable": true, "minimum_transfer_amount": 5, "maximum_transfer_amount": 1000 } ] } API Integration Once configured in the console, your currencies are immediately available through the INVO Network APIs for player balance management and transactions. Multi-Currency API Integration // Accessing configured currencies via API const SDK_KEY = 'ivsdk_your_64_character_key_here'; // Get player balances for all configured currencies async function getPlayerCurrencies(playerEmail) { const response = await fetch( `https://invo.network/api/player-balances/player/by-email/${encodeURIComponent(playerEmail)}`, { headers: { 'X-Game-Secret-Key': SDK_KEY } } ); const data = await response.json(); // Response includes all configured currencies console.log('Player Currencies:'); data.balances.forEach(balance => { console.log(`${balance.currency_name} (${balance.currency_symbol}): ${balance.total_balance}`); }); return data; } // Example response with multiple currencies: // { // "player": { // "player_id": 12345, // "player_name": "PlayerOne", // "player_email": "player@example.com" // }, // "balances": [ // { // "currency_id": 1, // "currency_name": "Gold Coins", // "available_balance": "1500.00", // "reserved_balance": "50.00", // "total_balance": "1550.00" // }, // { // "currency_id": 2, // "currency_name": "Premium Gems", // "available_balance": "250.00", // "reserved_balance": "0.00", // "total_balance": "250.00" // }, // { // "currency_id": 3, // "currency_name": "Event Tokens", // "available_balance": "15.00", // "reserved_balance": "0.00", // "total_balance": "15.00" // } // ], // "summary": { // "total_value": "1815.00", // "currency_count": 3, // "has_funds": true // } // } Currency Design Best Practices Follow these guidelines for optimal currency design and player experience: 💡 Design Guidelines • Keep currency names simple and memorable • Use 2-4 character symbols for clarity • Start with generous amounts (1000+ base currency) • Set transfer minimums to prevent spam • Consider maximum transfers for security • Upload recognizable symbol images ⚖️ Economic Balance • Plan currency inflation and deflation • Monitor cross-game transfer patterns • Adjust transfer limits based on usage • Consider multiple currency tiers • Test currency economy before launch • Have clear earning and spending sinks Currency Setup Checklist Complete these steps to successfully configure your game's virtual currencies: 🎯 Setup Tasks • ✅ Complete Step 3 of game registration wizard • ✅ Configure default currency name and symbol • ✅ Set appropriate starting player amounts • ✅ Upload currency symbol image (optional) • ✅ Configure transfer settings and limits • ✅ Test currency through player balance API 🔄 Post-Launch • ✅ Monitor currency usage and transfers • ✅ Add additional currencies as needed • ✅ Adjust transfer limits based on data • ✅ Update currency symbols and branding • ✅ Manage seasonal/event currencies • ✅ Optimize for cross-game participation Currency Value & the Fixed Exchange Rate Every INVO currency is pegged to a single platform-wide rate: 1 USD = 10 units (10 units per dollar). This rate is fixed and identical for every game — it is intentionally not configurable per currency. Why the rate is fixed A universal peg is what makes balances interchangeable across games and platforms . Because every currency shares the same relationship to USD, a cross-game transfer is a clean, known-value move — 100 units in one game is worth the same as 100 units in another. If each game set its own rate, cross-game transfers would require floating conversions and the interchange guarantee would break. Think of it as a shared settlement unit, not a per-game price. What you control • Currency name, symbol, and icon (branding) • Transfer rules, minimums, and limits • Your item prices — set in units (a 500-unit item = $50 at the peg) What's fixed (the peg) • 1 USD = 10 units , platform-wide • A $1 purchase always credits 10 units • A 1,000-unit withdrawal is always $100 Pricing tip: price your items and rewards in units , not dollars. The peg converts to and from USD automatically at purchase and withdrawal, so you never set a dollar value on your token — you set how many units something costs.

---

## Cross-Game Transfers

URL: https://docs.invo.network/docs/cross-game-transfers

Enable cross-game transfers in your game to allow players to move value between different games.

Cross-Game Transfers Enable secure currency transfers between different games in your ecosystem. Players can seamlessly move their virtual currency across game boundaries with SMS verification and secure claim codes. Overview How Cross-Game Transfers Work Initiate Transfer: Source game initiates transfer with player verification and target recipient phone SMS Verification: Player receives SMS PIN to verify the transfer Claim Code Generation: System generates secure claim code after verification Phone-Secured Claim: Only the specified target phone number can redeem the claim code Completion: Funds are transferred and both games receive fee distributions 🔒 BREAKING CHANGE: Phone-Based Security Cross-game transfers now require target_player_phone during initiation. The claim code can ONLY be redeemed by this exact phone number. • Transfer initiation now requires target_player_phone parameter • Claim codes are locked to the specified phone number • Phone mismatch during claim results in 403 Forbidden error • This prevents unauthorized claim code sharing Steam-purchased currency stays within Steam titles Currency a player buys through Steam can move among Steam-distributed games but not to non-Steam games, and non-Steam currency can't move into Steam titles. This containment is configured per-title by the platform and does not affect games that aren't Steam-distributed. • Moving more than the non-Steam-origin balance to a non-Steam destination returns 409 STEAM_VALUE_NON_TRANSFERABLE • Transferring from a non-Steam game into a Steam-distributed title returns 409 NON_STEAM_VALUE_INTO_STEAM_BLOCKED • Destination lists expose accepts_steam_origin_value so you can gray out non-Steam destinations for Steam-purchased balances ✅ Key Benefits • Secure SMS-based verification • Automatic fee distribution • Real-time balance updates • Comprehensive fraud protection • Support for different currencies ⚡ Fee Structure • Total Fee: 10% of transfer amount • Source Game: 3.5% fee share • Target Game: 3.5% fee share • Platform: 3% platform fee Authentication All transfer API endpoints require game authentication using your secret key: // Headers required for all requests X-Game-Secret-Key: your_game_secret_key Content-Type: application/json Transfer Flow 1 Initiate Transfer POST /api/transfers/initiate-transfer Request Body: { "client_request_id": "unique_transfer_id_123", "source_player_name": "John Doe", "source_player_email": "john@example.com", "source_player_phone": "+1234567890", "target_player_email": "jane@example.com", "target_player_phone": "+0987654321", "target_game_id": "456", "amount": "100.00" } Success Response: { "status": "success", "message": "Transfer initiated. Please verify with SMS PIN.", "transaction_id": "TXN_1234567890", "order_id": "TFRO_1640995200_ABC123", "transfer_details": { "source_game": "Game A", "target_game": "Game B", "target_game_id": "456", "currency": "Gold Coins", "currency_id": 1, "amount_initiated": "100.00", "fees_preview": { "total_fee": "10.00", "source_game_fee": "3.50", "target_game_fee": "3.50", "invo_fee": "3.00", "net_amount": "90.00" } }, "verification_required": { "phone_number_masked": "****7890", "pin_expires_in_minutes": 10 } } 2 Verify SMS PIN POST /api/transfers/verify-sms Request Body: { "transaction_id": "TXN_1234567890", "sms_pin": "123456" } Success Response: { "status": "success", "message": "SMS verification successful. Transfer pending claim.", "transaction_id": "TXN_1234567890", "claim_code": "KJMRS-47281", "new_balance": "500.00", "claim_instructions": { "message": "Provide this claim code to the intended receiver.", "target_game_id": "456", "target_game_name": "Game B", "claim_code_expires_at": "2024-01-02T10:00:00Z" }, "transfer_summary": { "amount_initiated": "100.00", "net_amount_for_claim": "90.00", "fees_deducted": "10.00", "source_player_current_available_balance": "500.00" } } Guardian Approval Holds When the transfer was initiated by a minor with a guardian on file, /verify-sms will not consume a PIN attempt and instead returns one of: • 202 GUARDIAN_APPROVAL_PENDING — held until the guardian approves via SMS • 410 GUARDIAN_APPROVAL_REJECTED / GUARDIAN_APPROVAL_EXPIRED — guardian rejected, or the approval window lapsed • 503 GUARDIAN_APPROVAL_CHECK_UNAVAILABLE — approval status could not be confirmed; retry shortly (no PIN attempt consumed) 3 Claim Transfer POST /api/transfers/claim-transfer Request Body: { "claim_code": "KJMRS-47281", "target_player_name": "Jane Smith", "target_player_email": "jane@example.com", "target_player_phone": "+1987654321", "target_currency_id": "2" } Success Response: { "status": "success", "message": "Transfer claimed successfully.", "transaction_id": "TXN_1234567890", "transfer_details": { "amount_received": "90.00", "source_game": "Game A", "target_currency": "Silver Coins", "target_player": "Jane Smith", "new_balance": "590.00" }, "completion_time": "2024-01-01T12:30:00Z", "order_id": "TFRO_1640995200_ABC123" } Additional Endpoints Get Transfer Status GET /api/transfers/{transaction_id}/status Check the current status of a transfer transaction. Returns: Transaction status, amount details, and completion information Get Transfer History GET /api/transfers/transfer-history?player_email=user@example.com Retrieve transfer history for a specific player. Parameters: player_email (required), limit (optional), offset (optional) Security Status GET /api/transfers/security-status?player_email=user@example.com Check security restrictions and rate limits for a player. Returns: Blocking status, velocity limits, and security metrics Security Features 🛡️ Fraud Protection • SMS PIN verification (10-minute expiry) • Claim code verification (24-hour expiry) • Rate limiting per player and IP • Velocity limits (hourly/daily) • Duplicate transfer detection • Circuit breaker protection ⚙️ Rate Limits • Initiate: 100/hour per player • SMS Verify: 40/hour per player • Claim: 30/hour per player • IP Limits: 150-200/hour • Transfer Velocity: 10/hour per player • Daily Amount: configurable per-game limit (default 1,000,000 currency units, adjustable by the platform) Error Handling Common Error Responses 400 - Bad Request Missing required fields, invalid amounts, or malformed data 401 - Unauthorized Invalid or missing game secret key 404 - Not Found Transaction, game, or player not found 409 - Conflict Duplicate client_request_id or transfer already processed 429 - Too Many Requests Rate limit exceeded, includes retry_after header Best Practices 💡 Implementation Tips • Always use unique client_request_id values to prevent duplicates • Implement proper error handling for all API responses • Store transaction_id for status checking and support • Validate phone numbers before initiating transfers • Handle rate limit responses gracefully with exponential backoff • Monitor transfer completion rates and failure reasons ⚠️ Important Notes • SMS PINs expire after 10 minutes • Claim codes expire after 24 hours • Expired transfers return funds to source player • Maximum 3 attempts for SMS verification • Maximum 5 attempts for claim code verification • All timestamps are in UTC format Testing in Sandbox Use sandbox environment for testing transfers without real SMS or charges: // Sandbox API Base URL https://sandbox-api.invo.com // Test SMS PIN (sandbox only) SMS PIN: 123456 // Test phone numbers +1555XXXXXXX (any valid format)

---

## Player Balance API

URL: https://docs.invo.network/docs/balance-overview

Learn how to check and manage player currency balances using Invo Network Balance API.

Player Balance API The Player Balance API provides real-time access to player currency balances across all registered games. Built to handle 60M+ users with sub-100ms response times and comprehensive balance management features. Real-time Balances Get instant access to current player balances with live updates and transaction processing. Multi-Currency Support Support multiple virtual currencies per game with automatic conversion and exchange rates. Reserved Balances Track reserved funds for pending transactions, ensuring accurate available balance calculations. High Performance Sub-100ms response times with advanced caching and optimized database queries. Batch Operations Efficiently query multiple player balances in a single API call for better performance. Balance Analytics Comprehensive balance history and analytics for player spending patterns and trends. Balance Structure Player balances are structured to provide comprehensive information about available funds, reserved amounts, and transaction history: { "player": { "player_id": 12345, "player_name": "John Doe", "player_email": "john.doe@example.com", "date_joined": "2024-01-15T10:30:00Z", "last_active": "2024-12-09T12:34:56Z" }, "balances": [ { "currency_id": 1, "currency_name": "Gold Coins", "currency_symbol": "GC", "available_balance": "150.00", // Funds available for spending "reserved_balance": "25.00", // Funds reserved for pending transactions "total_balance": "175.00", // Total balance (available + reserved) "last_transaction": "2024-12-09T11:45:30Z" }, { "currency_id": 2, "currency_name": "Premium Gems", "currency_symbol": "PG", "available_balance": "500.00", "reserved_balance": "0.00", "total_balance": "500.00", "last_transaction": "2024-12-08T15:22:10Z" } ], "summary": { "total_currencies": 2, "total_value_usd": "67.50", // Approximate USD value "has_funds": true, "last_updated": "2024-12-09T12:34:56Z" } } Balance Types Explained Available Balance Funds that can be immediately spent or transferred. This is the amount players can use for purchases or transfers. Use for: Purchase validation, transfer limits, spending checks Reserved Balance Funds temporarily held for pending transactions like transfers awaiting SMS verification or processing payments. Use for: Transaction tracking, pending operation displays Total Balance Complete balance including both available and reserved funds. Represents the player's total currency holdings. Use for: Portfolio displays, wealth tracking, analytics Core API Endpoints GET Get Player Balance GET /api/player-balances/player/{player_id} Retrieve current balance for a specific player by their player ID. Example Response: { "player": { "player_id": 12345, "player_name": "John Doe", "player_email": "john@example.com" }, "balances": [ { "currency_id": 1, "currency_name": "Gold Coins", "available_balance": "1500.00", "reserved_balance": "50.00", "total_balance": "1550.00" } ] } GET Get Balance by Email GET /api/player-balances/player/by-email/{email} Look up player balance using their email address - the most common method for game integration. Authentication Required: const response = await fetch( 'https://invo.network/api/player-balances/player/by-email/john@example.com', { headers: { 'X-Game-Secret-Key': 'ivsdk_your_key_here' } } ); POST Batch Balance Query POST /api/player-balances/batch Get balances for multiple players at once - perfect for leaderboards, tournaments, or analytics. Request Body: { "player_emails": [ "player1@example.com", "player2@example.com", "player3@example.com" ], "include_summary": true } Response: { "players": [ { "player_email": "player1@example.com", "balances": [...], "total_value": "1250.00" } ], "summary": { "total_players": 3, "total_value": "5430.00" } } Balance Operations Credit Operations Credit Player Balance Add funds to a player's available balance POST /api/player-balances/credit Purchase Rewards Credit currency after real money purchases POST /api/currency-purchases/confirm-payment Debit Operations Debit Player Balance Remove funds from a player's balance POST /api/player-balances/debit Item Purchases Debit currency for in-game item purchases POST /api/item-purchases/purchase-item Balance Validation Example Here's how to validate if a player has sufficient funds before processing a purchase: // Check if player has sufficient balance for a purchase async function validatePurchase(playerEmail, currencyId, amount) { try { // Get current player balance const response = await fetch( `https://invo.network/api/player-balances/player/by-email/${encodeURIComponent(playerEmail)}`, { headers: { 'X-Game-Secret-Key': SDK_KEY } } ); const balanceData = await response.json(); // Find the specific currency balance const currencyBalance = balanceData.balances.find( balance => balance.currency_id === currencyId ); if (!currencyBalance) { return { valid: false, error: 'Currency not found for player' }; } // Check if available balance is sufficient const availableAmount = parseFloat(currencyBalance.available_balance); const purchaseAmount = parseFloat(amount); if (availableAmount >= purchaseAmount) { return { valid: true, available_balance: availableAmount, purchase_amount: purchaseAmount, remaining_balance: availableAmount - purchaseAmount }; } else { return { valid: false, error: 'Insufficient funds', available_balance: availableAmount, required_amount: purchaseAmount, shortfall: purchaseAmount - availableAmount }; } } catch (error) { return { valid: false, error: 'Failed to validate balance: ' + error.message }; } } // Usage example const validation = await validatePurchase('player@example.com', 1, '25.00'); if (validation.valid) { console.log('Purchase approved:', validation); // Proceed with purchase } else { console.log('Purchase denied:', validation.error); // Show error to player } Performance & Optimization High-Performance Architecture The Balance API is optimized for high performance with several caching layers: • Redis Cache: Sub-10ms response times for frequently accessed balances • Database Optimization: Indexed queries and read replicas for scalability • CDN Distribution: Global edge caching for reduced latency • Batch Processing: Efficient multi-player balance queries • Real-time Updates: WebSocket connections for live balance changes • Auto-scaling: Handles 60M+ users with elastic infrastructure Rate Limits ⚡ Balance Query Limits • Individual queries: 2,000/minute per game • Batch queries: 100/minute per game • Email lookups: 1,500/minute per game • Burst allowance: 50% additional capacity 📊 Optimization Tips • Use batch queries for multiple players • Cache balance data on your side for 30-60 seconds • Implement exponential backoff for retries • Use webhooks for real-time balance updates Error Handling Common Error Responses 400 - Bad Request Invalid player ID, email format, or missing parameters 401 - Unauthorized Invalid or missing SDK key in Authorization header 404 - Not Found Player not found or no balance data available 429 - Too Many Requests Rate limit exceeded, implement exponential backoff 500 - Internal Server Error Temporary service issue, retry with exponential backoff Best Practices 💡 Integration Best Practices • Always check available_balance before allowing purchases or transfers • Use email-based lookups for better user experience • Implement client-side caching with 30-60 second TTL • Use batch queries when displaying multiple player balances • Handle rate limits gracefully with exponential backoff • Monitor balance query patterns and optimize accordingly ⚠️ Important Considerations • Reserved balances are not available for spending - always check available_balance • Player balances update in real-time across all games in the network • New players automatically receive starting currency amounts as configured • Balance history is maintained indefinitely for compliance and analytics • All monetary values are returned as strings to prevent floating-point precision issues • SDK keys must be used server-side only - never expose in client code Real-time Balance Updates WebSocket Integration For real-time balance updates in your game, consider implementing WebSocket connections: // WebSocket connection for real-time balance updates const socket = new WebSocket('wss://invo.network/ws/balance-updates'); socket.onopen = function() { // Subscribe to balance updates for specific players socket.send(JSON.stringify({ action: 'subscribe_player_balances', player_emails: ['player1@example.com', 'player2@example.com'], auth_token: 'Bearer ' + SDK_KEY })); }; socket.onmessage = function(event) { const update = JSON.parse(event.data); if (update.type === 'balance_update') { console.log('Balance updated:', update.player_email, update.new_balance); // Update your game UI with new balance updatePlayerBalanceUI(update.player_email, update.new_balance); } };

---

## Get Player Balance

URL: https://docs.invo.network/docs/get-balance
Endpoint: GET /api/player-balances/player/by-email/{email}

API documentation for retrieving player balance information using Invo Network API.

Get Player Balance Retrieve real-time player currency balances using a player ID or email address. Essential for purchase validation, balance displays, and currency management in your game. By Email Lookup Most common method for game integration GET /api/player-balances/player/by-email/{email} By Player ID Direct lookup when you have the player ID GET /api/player-balances/player/{player_id} Batch Queries Multiple players in a single request POST /api/player-balances/batch Get Balance by Email GET Player Balance by Email https://invo.network/api/player-balances/player/by-email/{email} 🎯 Most Common Method This is the primary method used by games since email addresses are the standard user identifier. Email addresses are automatically URL-encoded by the API. Request Headers X-Game-Secret-Key: your_game_secret_key_here Content-Type: application/json ⚠️ Use X-Game-Secret-Key header, NOT Authorization Bearer URL Parameters email (string, required) Player's email address - automatically URL encoded Unity Unity C# Example using System; using System.Collections; using UnityEngine; using UnityEngine.Networking; public class InvoPlayerBalance : MonoBehaviour { private const string API_BASE = "https://invo.network/api"; private const string GAME_SECRET_KEY = "your_game_secret_key_here"; // Corresponds to the full JSON response structure [System.Serializable] public class PlayerBalanceResponse { /* See full structure in 'Response Structure' section */ } public IEnumerator GetPlayerBalanceByEmail(string playerEmail, System.Action<PlayerBalanceResponse> onSuccess, System.Action<string> onError) { string encodedEmail = UnityWebRequest.EscapeURL(playerEmail); string url = $"{API_BASE}/player-balances/player/by-email/{encodedEmail}"; using (UnityWebRequest request = UnityWebRequest.Get(url)) { request.SetRequestHeader("X-Game-Secret-Key", GAME_SECRET_KEY); request.SetRequestHeader("Content-Type", "application/json"); yield return request.SendWebRequest(); if (request.result == UnityWebRequest.Result.Success) { PlayerBalanceResponse response = JsonUtility.FromJson<PlayerBalanceResponse>(request.downloadHandler.text); onSuccess?.Invoke(response); } else { onError?.Invoke($"HTTP Error {request.responseCode}: {request.error}"); } } } } Unreal Unreal Engine C++ Example // In your .h file #include "Http.h" // ... other includes USTRUCT(BlueprintType) struct FPlayerBalanceResponse { /* Add UPROPERTY fields for player, balances, summary */ }; DECLARE_DYNAMIC_MULTICAST_DELEGATE_OneParam(FOnBalanceResponse, const FPlayerBalanceResponse&, Response); // In your component/actor class public: UPROPERTY(BlueprintAssignable) FOnBalanceResponse OnBalanceReceived; UFUNCTION(BlueprintCallable) void GetPlayerBalanceByEmail(const FString& PlayerEmail); private: void OnHttpResponse(FHttpRequestPtr Request, FHttpResponsePtr Response, bool bWasSuccessful); // In your .cpp file void AYourActor::GetPlayerBalanceByEmail(const FString& PlayerEmail) { FHttpModule& HttpModule = FHttpModule::Get(); TSharedRef<IHttpRequest> Request = HttpModule.CreateRequest(); FString Url = FString::Printf(TEXT("https://invo.network/api/player-balances/player/by-email/%s"), *FGenericPlatformHttp::UrlEncode(PlayerEmail)); Request->SetURL(Url); Request->SetVerb("GET"); Request->SetHeader("X-Game-Secret-Key", "your_game_secret_key_here"); Request->OnProcessRequestComplete().BindUObject(this, &AYourActor::OnHttpResponse); Request->ProcessRequest(); } void AYourActor::OnHttpResponse(FHttpRequestPtr Request, FHttpResponsePtr Response, bool bWasSuccessful) { if (bWasSuccessful && Response.IsValid() && Response->GetResponseCode() == 200) { FPlayerBalanceResponse ResponseData; FJsonObjectConverter::JsonObjectStringToUStruct(Response->GetContentAsString(), &ResponseData, 0, 0); OnBalanceReceived.Broadcast(ResponseData); } else { // Handle error } } Godot Godot GDScript Example # InvoAPI.gd extends Node const API_BASE = "https://invo.network/api" const GAME_SECRET_KEY = "your_game_secret_key_here" signal balance_received(success, data) var http_request = HTTPRequest.new() func _ready(): add_child(http_request) http_request.request_completed.connect(self._on_request_completed) func get_player_balance(email: String): var encoded_email = email.uri_encode() var url = "%s/player-balances/player/by-email/%s" % [API_BASE, encoded_email] var headers = [ "X-Game-Secret-Key: %s" % GAME_SECRET_KEY, "Content-Type: application/json" ] http_request.request(url, headers, HTTPClient.METHOD_GET) func _on_request_completed(result, response_code, headers, body): if response_code == 200: var json = JSON.new() json.parse(body.get_string_from_utf8()) balance_received.emit(true, json.get_data()) else: balance_received.emit(false, {"error": response_code}) Response Structure Both email and ID lookups return the same comprehensive balance structure: ✅ Success Response (200) { "player": { "player_id": 12345, "player_name": "John Doe", "player_email": "john.doe@example.com", "date_joined": "2024-01-15T10:30:00Z", "last_active": "2024-12-09T12:34:56Z" }, "balances": [ { "currency_id": 1, "currency_name": "Gold Coins", "currency_symbol": "GC", "available_balance": "1500.00", "reserved_balance": "50.00", "total_balance": "1550.00", "last_transaction": "2024-12-09T11:45:30Z" } ], "summary": { "total_currencies": 1, "total_value_usd": "15.50", "has_funds": true, "last_updated": "2024-12-09T12:34:56Z" } } ❌ Error Response (404) { "error": "Player not found", "message": "No player found with email: invalid@example.com", "code": "PLAYER_NOT_FOUND", "timestamp": "2024-12-09T12:34:56Z" } Batch Balance Queries POST Multiple Player Balances https://invo.network/api/player-balances/batch 🚀 Efficient Bulk Queries Retrieve balances for up to 100 players in a single API call. Perfect for leaderboards, tournament displays, or analytics dashboards. Real-world Integration Examples 💰 Purchase Validation Always validate a player's balance on your server before allowing purchases or transactions to prevent client-side manipulation. // Server-side Node.js example async function validatePurchase(playerEmail, itemCost, currencyId) { try { const balanceData = await getPlayerBalanceByEmail(playerEmail); const currency = balanceData.balances.find(b => b.currency_id === currencyId); if (!currency || parseFloat(currency.available_balance) < itemCost) { console.error("Insufficient funds for player:", playerEmail); return { success: false, error: "Insufficient funds" }; } // If funds are sufficient, proceed with the transaction logic // (e.g., call another API to deduct the amount) console.log("Validation successful for player:", playerEmail); return { success: true, balance: currency.available_balance }; } catch (error) { console.error("Error during purchase validation:", error); return { success: false, error: "API error" }; } } 📊 In-Game Balance Display Create a component in your game engine to periodically refresh and display player currencies. // Unity C# Example for a UI display public class PlayerBalanceUI : MonoBehaviour { public TextMeshProUGUI goldText; public TextMeshProUGUI gemsText; private InvoPlayerBalance balanceAPI; void Start() { balanceAPI = gameObject.AddComponent<InvoPlayerBalance>(); InvokeRepeating(nameof(RefreshBalance), 1f, 30f); // Refresh every 30 seconds } void RefreshBalance() { StartCoroutine(balanceAPI.GetPlayerBalanceByEmail("player@example.com", OnBalanceUpdated, OnError)); } void OnBalanceUpdated(PlayerBalanceResponse response) { var gold = response.balances.FirstOrDefault(b => b.currency_name == "Gold Coins"); if(gold != null) goldText.text = $"Gold: {gold.available_balance}"; var gems = response.balances.FirstOrDefault(b => b.currency_name == "Premium Gems"); if(gems != null) gemsText.text = $"Gems: {gems.available_balance}"; } void OnError(string error) { Debug.LogError("Could not refresh balance: " + error); } } Performance & Caching Optimization Strategies Implement these strategies on your server to minimize API calls and improve player experience: Server-Side Caching • Use Redis or Memcached to cache balance data for 30-60 seconds. • Invalidate the cache immediately after a player completes a transaction. • Serve cached data to reduce latency on repeated requests. Smart Refresh Patterns • Refresh data from the API only when the cache expires or is invalidated. • Use batch requests for leaderboards instead of individual lookups. • Implement exponential backoff for retries on server errors. Rate Limits & Error Handling API Rate Limits • Email/ID Lookups: 1,500 requests/minute per game • Batch Queries: 100 requests/minute per game • Exceeding limits will result in a 429 error. Common Error Codes • 400 Bad Request: Invalid email format or player ID. • 401 Unauthorized: Invalid or missing SDK key. • 404 Not Found: The requested player does not exist. • 429 Too Many Requests: Rate limit exceeded. Check `Retry-After` header. • 500 Internal Server Error: A server-side issue occurred. Retry with backoff.

---

## Currency Purchase API

URL: https://docs.invo.network/docs/currency-purchase
Endpoint: POST /api/checkout-sessions

Implement currency purchase functionality in your game using Invo Network Purchase API.

Currency Purchase Integration Real-money top-ups for your branded in-game currency. Players check out on an INVO-hosted page, payments process server-side, and the player's balance is credited automatically. No payment UI to build, no card data on your servers. Note on minor accounts: currency top-ups are not gated by Invo's guardian-approval flow. The guardian's approval lives at the parent's payment-method level (their card / bank), not at the Invo API level — Invo trusts that whatever card was used to fund the purchase is authorized by the account holder. See Guardian Approval for the full scope. Hosted Checkout Your backend mints a short-lived signed session URL. You open that URL in an iframe or WebView. Player completes the purchase. INVO credits the player's balance and (optionally) notifies your backend via webhook. What you get • Card data never crosses your servers (SAQ-A scope) • Strong Customer Authentication (3DS) where required • Saved card support for returning players • Fraud detection + velocity limits • Mobile-optimised checkout UI • Server-side credit applied on payment success How it works 1. Server: POST /api/checkout/sessions with player email + USD amount 2. Get back a signed checkout_url (JWT, 15 min TTL, single-use) 3. Open that URL in iframe/WebView 4. Player pays 5. Listen for the INVO_CHECKOUT_COMPLETE postMessage and/or the server-to-server webhook View Full Integration Guide → Step-by-step 1. Create a checkout session (server-side) Call this from your game backend. The SDK key never leaves your server. POST https://invo.network/api/checkout/sessions Headers: X-Game-Secret-Key: ivsdk_<your_sdk_key> Content-Type: application/json Body: { "player_email": "player@example.com", "usd_amount": "10.00", "rail": "platform", "success_url": "https://yourgame.com/store/success", "cancel_url": "https://yourgame.com/store/cancel", "metadata": { "your_user_id": "u_42", "coin_pack": "starter" } } Response 201: { "session_id": "<jti>", "checkout_url": "https://invo.network/checkout?session=<jwt>", "expires_at": "2024-12-09T12:49:56Z", "expires_in_seconds": 900 } checkout_url contains a 15-minute signed token. Single-use — reusing the same URL after a successful payment returns 409 SESSION_ALREADY_CONSUMED . usd_amount must be greater than 0 and at most 999.99 . In sandbox the checkout_url host is sandbox.invo.network (the page is at /checkout , no /sandbox prefix); validate that origin in your iframe postMessage listener accordingly. Payment rail (optional rail ): choose how the player pays. Defaults to platform . The hosted page renders the right experience for each — all branded as INVO. • platform — cards plus Apple Pay, Google Pay, and Link , with full international billing-address support (default). Wallets appear automatically on supported devices; there is no extra fee and no app-store commission (this is a web checkout). • game — regional / game-store payment methods, presented in-page. • steam — for Steam titles, use the dedicated Steam purchase flow (server-to-server init/finalize). A steam checkout session only renders an in-client hand-off message; it does not by itself drive the Steam purchase. 2. Open the URL in a WebView/redirect or an iframe The hosted page handles cards, Apple Pay / Google Pay / Link, international billing addresses, 3DS challenges (including a top-level break-out when embedded), saved-card selection, and the actual charge. Two ways to present it: • WebView / full-page redirect (recommended, works everywhere): on success the page redirects to your success_url . • Embedded <iframe> : works out of the box — set iframe.src = checkout_url (any https site may frame the page). When embedded, the page does not redirect your top window; listen for the INVO_CHECKOUT_COMPLETE postMessage (below). Optionally, ask INVO to restrict framing to your specific origin(s) for extra hardening. // Web (WebGL build / browser) const iframe = document.createElement('iframe'); iframe.src = checkoutUrl; iframe.style.cssText = 'width:480px; height:720px; border:0;'; document.body.appendChild(iframe); // Mobile (Unity, Unreal, native) // Open checkout_url in your platform's WebView component. 3. Listen for completion Two signals — use whichever fits your stack. The server-to-server webhook is the authoritative one. Browser postMessage (UX hint) window.addEventListener('message', (event) => { if (event.data?.type === 'INVO_CHECKOUT_COMPLETE') { const { status, new_balance, currency_name, transaction_id } = event.data.data; if (status === 'success') { updatePlayerBalance(new_balance); } } }); postMessage is not signed. Treat it as a UX hint to refresh the player's balance optimistically. For ledger-of-record accuracy, rely on the webhook below or re-read the player's balance from the API. Server-to-server webhook (authoritative) POST <your_webhook_url> Headers: X-Invo-Signature: t=<unix_timestamp>,v1=<hex_hmac_sha256> X-Invo-Event-Id: <uuid> # unique per delivery (changes on retry/replay) X-Invo-Idempotency-Key: <stable id> # dedupe on THIS Body: { "event_id": "evt_01HX...", "event_type": "purchase.completed", "created_at": "2024-12-09T12:34:56Z", "tenant_id": "<your game_id>", "data": { "transaction_id": "txn_...", "order_id": "ord_...", "player_email": "player@example.com", "identity_id": "f3a1b8c0d4e5...", "usd_amount": "10.00", "currency_amount": "100", "currency_name": "Gold Coins", "metadata": { "your_user_id": "u_42", "coin_pack": "starter" } } } Verify the HMAC-SHA256 signature using your tenant's webhook signing secret. Dedupe on X-Invo-Idempotency-Key — it is stable across retries and replays. Do not dedupe on X-Invo-Event-Id : that is unique per delivery and changes on every retry/replay. Reject timestamps older than 5 minutes. Direct API (advanced) If you operate your own PCI-compliant card collection (rare — most integrations should use hosted checkout), you can post a tokenised payment method directly: POST https://invo.network/api/currency-purchases/purchase-currency Headers: X-Game-Secret-Key: ivsdk_<your_sdk_key> Content-Type: application/json Body: { "player_email": "player@example.com", "usd_amount": "10.00", "payment_method_id": "<tokenised_card_id_from_your_card_collector>", "purchase_reference": "<uuid_v4>", // REQUIRED — see "Idempotency" below "metadata": { "your_user_id": "u_42" } } Possible responses: 200, status:"success" — purchase complete; body has transaction_id + new_balance 200, status:"requires_action" — 3-D Secure needed; see "Handling 3-D Secure" below 200, status:"success", duplicate:true — replay of a prior completed purchase_reference 409, status:"pending", duplicate:true — purchase already in flight for this purchase_reference 400, error_code:"MISSING_PURCHASE_REFERENCE" — field omitted 400, error_code:"INVALID_PURCHASE_REFERENCE" — field >255 chars 4xx — validation, rate limit, or card-issuer decline (see error envelope) Branch on the status field — never treat a non-success response as a decline. requires_action is a normal step for many cards (mandatory for European cards under SCA), not a failure; prompting the player for a different card here is the wrong move. Idempotency — purchase_reference is REQUIRED Every call to /purchase-currency must include a stable, unique purchase_reference (a UUID v4 is fine). This is the single most important field for avoiding duplicate charges on a flaky network. • Generate it once per logical purchase attempt — at the moment the player taps "Buy", not per HTTP call. • Resend the same value on every retry. If the network dropped mid-response, INVO returns the prior result (HTTP 200, duplicate: true ) instead of charging the card a second time. • Generate a new one for a genuinely new purchase (e.g. the player cancels, then taps Buy again). • Max length 255 chars; uniqueness is per game. Backward compatibility: the field was previously documented as client_request_id . The API still accepts that name as an alias. New integrations should send purchase_reference ; existing integrations sending client_request_id continue to work without change. What changes if you omit it (or send a fresh value each retry): a network blip will charge the card twice. INVO can refund, but the player saw a double charge and the partner saw a dispute risk. The 400 error you now get for omission is intentional — it forces the safer pattern. Handling 3-D Secure (status: requires_action) When a card needs Strong Customer Authentication, /purchase-currency returns HTTP 200 with status: "requires_action" . No money has been charged and nothing has failed — the cardholder just has to complete a bank challenge. Step 1. The response carries what you need to run the challenge: { "status": "requires_action", "client_secret": "pi_xxx_secret_xxx", "payment_intent_id": "pi_xxx", "order_id": "ord_xxx", "new_balance": null } Step 2. Run the 3-D Secure challenge on the client using the JavaScript SDK your card collector provided, passing the client_secret — this presents the bank's authentication step to the player: // Web — pseudocode. INVO's auth challenge uses the automatic-confirmation // flow, so call your card-collector SDK's "confirm" variant (the one that // confirms AND runs the challenge in a single call), NOT a manual-server- // confirm-only "handle action" variant. If your SDK exposes both, the // confirm variant is the correct call here. const { error, paymentIntent } = await processor.confirmCardPayment(client_secret); if (error) { // Player abandoned 3DS, bank declined, etc. No money moved. // Show the user a retry / different-card prompt. } else if (paymentIntent && paymentIntent.status === 'succeeded') { // 3DS passed and the auth challenge completed. Now proceed to Step 3 // so INVO credits the player's branded currency. } // Mobile: use the iOS / Android SDK from your card collector. Same rule — // pick the confirm-payment variant, not a manual-confirm-only handler. // This step talks directly to your card processor and does not use your INVO key. Common gotcha: if your SDK exposes both a "handle next action / handle card action" call and a "confirm payment" call, the manual-handler variant will fail with a runtime error along the lines of "the auth challenge does not require manual server-side confirmation — use the confirm variant instead" . INVO challenges use the automatic-confirmation flow; always pick the SDK's confirm-payment method here. Step 3. Once the SDK reports success, finalise the purchase server-side — this is where the player's branded currency is credited: POST https://invo.network/api/currency-purchases/confirm-payment Headers: X-Game-Secret-Key: ivsdk_<your_sdk_key> Content-Type: application/json Body: { "payment_intent_id": "pi_xxx", "order_id": "ord_xxx" } Response 200: { "status": "success", "transaction_id": "txn_...", "order_id": "ord_xxx", "new_balance": "100", "already_processed": false } confirm-payment is idempotent — a retry, or a late call after INVO has already credited the purchase, returns already_processed: true instead of crediting twice. Spending limits INVO enforces hourly, daily, and monthly USD caps per (player_email, game). A purchase that would exceed any cap returns HTTP 429 with error: "spending_limit_exceeded" and a human-readable message naming the cap that was hit. Only successful purchases consume the cap. Declined cards, abandoned 3-D Secure challenges, and circuit-breaker rejections leave the cap untouched, so a player whose card just failed can immediately try again with a different card. Defaults are configurable per environment; ask your INVO contact if you need higher limits for a specific tenant. What hosted checkout handles for you Fast Checkout Typical checkout completes in under 30 seconds. Players get their currency the moment payment confirms. Compliance Out of the Box Your scope is SAQ-A — no card data crosses your servers. We handle PCI, 3DS, and dispute messaging end-to-end. Global Reach Major credit and debit cards plus regional payment methods supported worldwide. Player Experience Saved Cards for Returning Players Players can save payment methods for one-tap re-purchase. The selector appears automatically when a returning player checks out. Saved-card flow 1 Player clicks "Buy Currency" → card selector modal appears 2 Saved cards listed with brand, last 4 digits, and expiration 3 Player picks a saved card or selects "Use New Card" 4 Review-purchase modal confirms the amount and card 5 Player confirms → instant purchase, no card re-entry Zero extra integration: saved cards work automatically with hosted checkout. Review & Confirmation Before charging a saved card we show a friendly review dialog. This satisfies FTC guidance on surprise charges and reduces accidental purchases. Review dialog Friendly UI — checkmark icon, clear "Review Your Purchase" header. Purchase summary — amount, currency credited, card last 4. Explicit "Complete Purchase" button — no implicit consent. Easy cancel — clear secondary action. First-Time Purchase When a player has no saved cards, they go straight to the secure card-entry page. From there they can: Enter card details on the INVO-hosted page (your servers never see them) Opt to save the card for next time (default-on, easy to opt out) Complete 3DS challenges if their bank requires SCA See instant confirmation and have currency credited automatically Outbound webhook events INVO emits server-to-server webhooks for every meaningful event on a purchase. All deliveries carry an X-Invo-Signature HMAC header, an X-Invo-Event-Id (unique per delivery), and an X-Invo-Idempotency-Key (stable across retries/replays — dedupe on this). Retries follow a back-off schedule (30s, 2m, 10m, 1h, 6h, 24h). Event type When it fires Balance effect purchase.completed Payment cleared on any payment method + branded currency credited. +credit purchase.failed Card declined, 3-D Secure abandoned, payment cancelled, or async payment failed. none purchase.refunded Full or partial refund issued through INVO's admin tooling. Partial refunds proportionally debit the player's branded currency; the order stays in completed status until the charge is fully refunded. −debit (full or partial) purchase.disputed Chargeback opened by the issuer. Fires again on close with dispute_status = won / lost . −debit on lost purchase.fraud_warning Early-fraud-warning signal from the card network — the issuing bank flagged the charge as likely fraudulent. Chargeback probable. none (advisory) purchase.refunded — full refund { "event_id": "evt_01HX...", "event_type": "purchase.refunded", "tenant_id": "<your game_id>", "data": { "order_id": "ORD_...", "transaction_id": "txn_...", "payment_intent_id": "pi_...", "charge_id": "ch_...", "usd_refunded": "10.00", "usd_original": "10.00", "fully_refunded": true, "currency_debited": "100", "new_balance": "0", "currency_name": "Gold Coins", "order_status": "refunded" } } purchase.disputed — opened { "event_id": "evt_01HX...", "event_type": "purchase.disputed", "tenant_id": "<your game_id>", "data": { "order_id": "ORD_...", "transaction_id": "txn_...", "payment_intent_id": "pi_...", "charge_id": "ch_...", "dispute_id": "dp_...", "reason": "fraudulent", "usd_amount": "10.00" } } purchase.disputed — closed (lost — clawback applied) { "event_type": "purchase.disputed", "data": { "order_id": "ORD_...", "dispute_id": "dp_...", "dispute_status": "lost", "currency_debited": "100", "new_balance": "0" } } purchase.fraud_warning — Early Fraud Warning { "event_id": "evt_01HX...", "event_type": "purchase.fraud_warning", "tenant_id": "<your game_id>", "data": { "order_id": "ORD_...", "transaction_id": "txn_...", "payment_intent_id": "pi_...", "charge_id": "ch_...", "fraud_type": "made_with_stolen_card", "actionable": true, "usd_amount": "10.00", "recommendation": "consider_refund" // or "monitor" } } purchase.failed — payment canceled / declined { "event_type": "purchase.failed", "data": { "payment_intent_id": "pi_...", "order_id": "ORD_...", "player_email": "player@example.com", "usd_amount": "10.00", "failure_code": "card_declined", // or "payment_canceled" "failure_message": "Your card was declined." } } Order status lifecycle Every purchase passes through a deterministic set of states. The /order-details endpoint returns the current state and timestamps; INVO retains a full append-only audit trail of every transition (server-side, available to support and finance on request). pending_payment — order created, waiting on the payment processor. requires_action — 3-D Secure challenge pending on the cardholder. completed — charge confirmed, branded currency credited. failed — card declined or async payment failed. cancelled — the payment was cancelled (player abandoned 3-D Secure, the payment session timed out, or an admin cancelled). refunded — full refund processed; currency debited. disputed_lost — chargeback resolved against the merchant; currency clawed back. Webhook delivery + the order-details endpoint are the two authoritative read paths. Do not infer state from response status codes alone. Platform Support Hosted checkout works in iframe/WebView on every major game platform: 🎮 Unity WebGL & Mobile 🔷 Unreal Engine All Platforms 📱 iOS Native & Hybrid 🤖 Android Native & Hybrid Platform-specific examples → Why hosted checkout Less work, faster ship Skip the months it takes to build a payment UI, integrate a card processor, pass a PCI audit, and run dispute operations. • No payment UI to build • No PCI audit (SAQ-A scope) • No fraud-management infrastructure • No SCA / 3DS implementation Enterprise features built in The features production payment systems need ship by default — not as paid add-ons. • Saved cards / one-tap re-buy • 3D Secure / Strong Customer Authentication • Fraud detection + velocity limits • Dispute lifecycle + automatic balance reconciliation Ready to integrate? The full integration guide has platform-specific code for Unity, Unreal, iOS, and Android. View Integration Guide Register Your Game

---

## Steam Payments

URL: https://docs.invo.network/docs/steam-purchase
Endpoint: POST /api/currency-purchases/steam/init-purchase

Accept real-money currency top-ups through Steam in-game purchasing with the Invo Network Steam payment rail.

Steam Payments If your game is on Steam, players can top up your branded in-game currency without ever leaving the Steam client. They pay with their Steam Wallet — or any card, PayPal, or regional method already linked to their Steam account — and approve the charge in Steam's own purchase overlay. No checkout page, no card form, no redirect: the payment happens in the storefront the player already trusts, and INVO credits their balance the instant the charge is captured. Zero Steam-side setup Every INVO game distributed on Steam shares one INVO Steam application for currency purchases. You do not register your own Steam app for this, you do not request or store a Steam publisher key, and there is no per-game Steam configuration. INVO operates the Steam application, holds the publisher credentials server-side, and reconciles settlement. Your integration is just three HTTP calls and one Steam SDK callback. You don't need a Steam partner account for payments You don't need a Steam publisher Web API key You don't need any per-game Steam setup in INVO How it works Steam splits a micro-transaction into two phases. First the player authorizes the charge in the Steam client. Then the merchant captures it. INVO drives both phases and credits the player's branded currency the moment the charge is captured — the same credit-on-capture model as card purchases. Three parties are involved: your game (client + backend), INVO , and Steam . Your game backend makes two server-to-server calls to INVO; your game client handles one Steam SDK callback in between. The handshake: 1 Initialize Your backend calls /steam/init-purchase . INVO creates the order and opens a transaction on Steam. Steam then shows the purchase overlay to the player. 2 Authorize The player approves the charge in Steam. Your game client receives the MicroTxnAuthorizationResponse_t Steam SDK callback. 3 Finalize Your backend calls /steam/finalize-purchase . INVO verifies the authorization with Steam, captures the charge, and credits the player. Why two server calls? Your X-Game-Secret-Key authenticates the INVO API and must never ship inside a game client. So the game client never calls INVO directly for payments — it calls your backend, and your backend calls INVO. The only thing the client touches is the Steam SDK callback. Step 1 — Initialize the purchase (backend) When the player picks a currency pack, your backend calls INVO. You pass the player's 64-bit steamid — your game client already has it from the Steamworks SDK and forwards it to your backend — and the USD amount. POST https://invo.network/api/currency-purchases/steam/init-purchase Headers: X-Game-Secret-Key: ivsdk_<your_sdk_key> Content-Type: application/json Body: { "player_email": "player@example.com", "steamid": "76561198000000000", "usd_amount": "10.00", "purchase_reference": "<uuid_v4>", "player_name": "PlayerOne" } Response 200: { "status": "pending_authorization", "order_id": "ord_a1b2c3...", "steam_transid": "350000123456789", "new_balance": null } player_email (required) — identifies the INVO player whose branded-currency balance is credited. A player row is created on first purchase if it doesn't exist. steamid (required) — the 64-bit Steam ID of the account paying. Steam shows the authorization overlay to this account. Must be numeric. usd_amount (required) — the charge in USD, as a string. Maximum 999.99 per transaction. purchase_reference (required) — your idempotency key (UUID v4 recommended, max 255 chars). Replaying the same value returns the existing order ( 409 , duplicate ) instead of creating a second charge — safe to retry on a network failure. Omitting it returns 400 MISSING_PURCHASE_REFERENCE ; sending one longer than 255 chars returns 400 INVALID_PURCHASE_REFERENCE . The field client_request_id is accepted as an alias for backward compatibility. player_name (optional) — display name; falls back to the local-part of the email if omitted on first purchase. order_id (response) — keep this. Your game client passes it back to your backend for Step 3. As soon as init-purchase succeeds, Steam presents its purchase dialog to the player inside the Steam overlay. You do not trigger any UI yourself. Step 2 — The player authorizes (game client) Steam delivers the player's decision to your game client through the Steamworks SDK callback MicroTxnAuthorizationResponse_t . The callback carries m_bAuthorized (1 if the player approved), m_unAppID , and m_ulOrderID — the numeric order id, useful if you have several purchases in flight at once. When the player approves, tell your backend to run Step 3. INVO never sees this callback; it is strictly between Steam and your game client. Unity (C#, Steamworks.NET) using Steamworks; using UnityEngine; public class InvoSteamPurchase : MonoBehaviour { private Callback<MicroTxnAuthorizationResponse_t> _authCallback; private string _pendingOrderId; void Start() { // Register the Steam authorization callback once. _authCallback = Callback<MicroTxnAuthorizationResponse_t>.Create(OnSteamAuthorized); } // Called when the player taps "Buy" on a currency pack. public async void BuyCurrency(string usdAmount) { ulong steamId = SteamUser.GetSteamID().m_SteamID; // Ask YOUR backend to start the purchase. Your backend calls INVO's // /steam/init-purchase with your X-Game-Secret-Key (never in the client). var result = await MyGameBackend.StartSteamPurchase(usdAmount, steamId); _pendingOrderId = result.OrderId; // INVO's "ord_..." id // Steam now shows the purchase overlay to the player automatically. } // Steam fires this when the player approves or declines. private void OnSteamAuthorized(MicroTxnAuthorizationResponse_t cb) { if (cb.m_bAuthorized == 1) { // Approved — ask your backend to finalize (it calls INVO). MyGameBackend.FinalizeSteamPurchase(_pendingOrderId); } else { // Declined or cancelled — nothing was charged. } } void OnDestroy() => _authCallback?.Dispose(); } Unreal Engine (C++, Steamworks SDK) #include "steam/steam_api.h" class FInvoSteamPurchase { public: // Called when the player taps "Buy" on a currency pack. void BuyCurrency(const FString& UsdAmount) { const uint64 SteamId = SteamUser()->GetSteamID().ConvertToUint64(); // Ask YOUR backend to start the purchase. Your backend calls INVO's // /steam/init-purchase with your X-Game-Secret-Key (never in the client). MyGameBackend->StartSteamPurchase(UsdAmount, SteamId, [this](const FString& OrderId) { PendingOrderId = OrderId; // INVO's "ord_..." id // Steam shows the purchase overlay to the player automatically. }); } private: FString PendingOrderId; // Steam fires this when the player approves or declines. STEAM_CALLBACK(FInvoSteamPurchase, OnSteamAuthorized, MicroTxnAuthorizationResponse_t); }; void FInvoSteamPurchase::OnSteamAuthorized(MicroTxnAuthorizationResponse_t* cb) { if (cb->m_bAuthorized) { // Approved — ask your backend to finalize (it calls INVO). MyGameBackend->FinalizeSteamPurchase(PendingOrderId); } // else: declined or cancelled — nothing was charged. } The callback only reports the player's intent — it is not proof of payment. INVO independently re-verifies the authorization with Steam in Step 3 before any money moves or any currency is credited. Step 3 — Finalize the purchase (backend) After your client reports an authorized callback, your backend calls INVO with the order_id from Step 1. INVO verifies the authorization with Steam server-side, captures the charge, and credits the player's branded currency in one atomic step. POST https://invo.network/api/currency-purchases/steam/finalize-purchase Headers: X-Game-Secret-Key: ivsdk_<your_sdk_key> Content-Type: application/json Body: { "order_id": "ord_a1b2c3..." } Response 200: { "status": "success", "transaction_id": "txn_...", "order_id": "ord_a1b2c3...", "new_balance": "100", "already_processed": false } finalize-purchase is idempotent — a retry, or a duplicate call, returns already_processed: true and never credits twice. If the player has not finished authorizing yet, it returns 409 with status: "not_authorized" — wait for the Steam callback and call again. Responses & error handling HTTP status What it means / what to do 200 success Purchase captured and currency credited. Read new_balance . 200 pending_authorization init-purchase succeeded; the player must now authorize in Steam. 409 not_authorized finalize was called before the player approved. Wait for the Steam callback, then retry. 409 duplicate This purchase_reference already has an order. Use the returned order_id . 502 steam_error Steam rejected or could not process the call. Safe to retry. 503 service_unavailable Steam is temporarily unreachable (circuit breaker open). Retry shortly. Even if your backend never gets to call finalize-purchase — a crash, a dropped connection — INVO's reconciliation poller independently detects the authorized Steam transaction and credits the player. A missed finalize call delays the credit; it never loses it. Refunds Steam refunds are reconciled automatically — you do not handle them. When a Steam purchase is refunded, INVO debits (claws back) the branded currency it originally credited, exactly as it does for a card refund, and emits the purchase.refunded webhook to your tenant. The clawback is allowed to drive a balance negative if the player has already spent the currency — the negative balance is settled against the player's next top-up. This keeps your ledger honest without blocking the refund. Sandbox testing In the INVO sandbox environment the Steam rail runs against Steam's ISteamMicroTxnSandbox interface — the identical init / authorize / finalize handshake against Steam's test system, with no real money charged. The endpoint paths, request bodies, and responses are exactly the same as production, so the integration you build in sandbox ships unchanged. Run the full three-step flow there — including a declined authorization and a refund — before going live. See Sandbox Testing . Good to know Server-side only Both /steam/* endpoints require your X-Game-Secret-Key and must be called from your backend. The game client only ever handles the Steam SDK callback. Credit on capture The player's branded currency is credited the instant finalize-purchase captures the charge — no waiting on Steam's multi-day settlement cycle. Reconciliation safety net If your backend ever misses the finalize call, INVO's poller detects the authorized transaction and credits the player anyway. Refunds are caught the same way. One balance, every rail Steam purchases credit the same branded-currency balance as card purchases and cross-game transfers. To your players, the payment rail is invisible. Idempotent by design purchase_reference on init and the order_id on finalize make every call safe to retry — no double charges, no double credits. Authorization re-verified A client callback can be spoofed; INVO doesn't trust it. Every finalize independently re-checks the authorization with Steam before capturing.

---

## Item Purchase API

URL: https://docs.invo.network/docs/item-purchase
Endpoint: POST /api/item-purchases/purchase-item

Enable item purchases in your game using Invo Network Item Purchase API for seamless transactions.

Item Purchase API Allow players to purchase in-game items using their existing currency balances. This API provides a secure, transactional method for managing your in-game economy. Note on minor accounts: item purchases are intentionally not gated by guardian approval, even when the buyer is flagged as a minor. The guardian's approval was given when the currency entered the wallet (via a guardian-approved transfer or send); a second gate at spend time is redundant friction. Minor users can purchase items normally. See Guardian Approval for the full scope. Purchase Item The core endpoint to execute an item purchase. POST /api/item-purchases/purchase-item Purchase History Retrieve a specific player's item purchase history. GET /api/item-purchases/player-purchase-history Order Details Get detailed financial records for a specific order. GET /api/item-purchases/order-details 1. Purchase Item Endpoint POST /api/item-purchases/purchase-item Securely processes an item purchase by deducting from a player's balance. Security Warning This endpoint must only be called from your secure game server. Your server should first validate the player's session and then make this API call. Never call it directly from a game client. Authentication Required All requests to this endpoint must include your game's secret key in the request headers: X-Game-Secret-Key: your_game_secret_key_here You can find your game's secret key in your Invo dashboard under Game Settings → API Keys. Request Body Parameters Parameter Type Description client_request_id string A unique ID generated by your client to ensure idempotency. See section below. player_email string The email address of the purchasing player. player_name string The player's current display name. item_id string Your internal unique identifier for the item. item_name string The display name of the item. item_quantity integer The number of units being purchased. unit_price string The price of a single unit of the item, as a string. total_price string The total price for the purchase (quantity * unit_price). item_category string (optional) A category for the item (e.g., "Weapons", "Skins"). item_description string (optional) Free-form description for receipts and history views. player_phone string (optional) E.164 phone number; recorded if the player auto-creates on this call. Successful response (HTTP 200) { "status": "success", "message": "Item purchased successfully", "transaction_id": "TXN...", "order_id": "ORD...", "new_balance": "900.00", "previous_balance": "1000.00", "currency_name": "Gold Coins", "purchase_details": { "item_id": "legendary_sword_001", "item_name": "Legendary Sword", "item_description": "A powerful weapon", "item_category": "weapons", "quantity": 1, "unit_price": "100.00", "total_price": "100.00", "currency_name": "Gold Coins", "purchased_by": "Player Name" }, "balance_info": { "previous_balance": "1000.00", "amount_spent": "100.00", "new_balance": "900.00" }, "financial_breakdown": { "total_paid": "100.00", "developer_revenue": "90.00", "platform_fee": "10.00" }, "player": { "player_id": 102, "player_email": "player@example.com", "player_name": "Player Name" } } Read the player's spendable balance from the top-level new_balance — it is the canonical post-write value (the same number is mirrored in balance_info.new_balance for legacy callers). Treat it as eventually-consistent for batch reads. financial_breakdown reflects the network's current item-purchase fee split (90% to you, 10% network fee). 2. Idempotency and Safe Retries Preventing Duplicate Purchases Network errors can happen. To prevent a player from being charged twice for the same item if a request is retried, you must provide a unique client_request_id for every purchase attempt. If our server receives a request with a client_request_id it has already processed, it will not create a new transaction. Instead, it will return a 409 Conflict error, letting you know the purchase is already complete. A good practice is to generate a UUID on your client for each new purchase action. 3. Code Implementation Examples Unity Unity C# (Server-Side Logic) // This function MUST be on your secure server. public IEnumerator PurchaseItem(string playerEmail, string itemName, string itemId, int quantity, float price, Action<string> onSuccess, Action<string> onError) { string url = "https://invo.network/api/item-purchases/purchase-item"; var requestData = new { client_request_id = System.Guid.NewGuid().ToString(), // Generate a unique ID for each attempt player_email = playerEmail, player_name = "Player fetched from your DB", item_id = itemId, item_name = itemName, item_quantity = quantity, unit_price = price.ToString("F2"), total_price = (price * quantity).ToString("F2") }; string jsonBody = JsonUtility.ToJson(requestData); using (UnityWebRequest request = new UnityWebRequest(url, "POST")) { byte[] bodyRaw = System.Text.Encoding.UTF8.GetBytes(jsonBody); request.uploadHandler = new UploadHandlerRaw(bodyRaw); request.downloadHandler = new DownloadHandlerBuffer(); request.SetRequestHeader("X-Game-Secret-Key", "your_game_secret_key_here"); request.SetRequestHeader("Content-Type", "application/json"); yield return request.SendWebRequest(); if (request.result == UnityWebRequest.Result.Success) { onSuccess?.Invoke(request.downloadHandler.text); } else { onError?.Invoke(request.downloadHandler.text); } } } Unreal Unreal C++ (Server-Side Logic) // This function MUST be on your secure server. void AYourGameBackend::PurchaseItem(const FString& PlayerEmail, const FString& ItemId, int32 Quantity, float Price) { TSharedPtr<FJsonObject> RequestObj = MakeShareable(new FJsonObject); RequestObj->SetStringField("client_request_id", FGuid::NewGuid().ToString()); RequestObj->SetStringField("player_email", PlayerEmail); RequestObj->SetStringField("player_name", "Player Name from DB"); RequestObj->SetStringField("item_id", ItemId); RequestObj->SetStringField("item_name", "Item Name from DB"); RequestObj->SetNumberField("item_quantity", Quantity); RequestObj->SetStringField("unit_price", FString::Printf(TEXT("%.2f"), Price)); RequestObj->SetStringField("total_price", FString::Printf(TEXT("%.2f"), Price * Quantity)); FString RequestBody; TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&RequestBody); FJsonSerializer::Serialize(RequestObj.ToSharedRef(), Writer); TSharedRef<IHttpRequest> Request = FHttpModule::Get().CreateRequest(); Request->SetURL("https://invo.network/api/item-purchases/purchase-item"); Request->SetVerb("POST"); Request->SetHeader("X-Game-Secret-Key", "your_game_secret_key_here"); Request->SetHeader("Content-Type", "application/json"); Request->SetContentAsString(RequestBody); Request->OnProcessRequestComplete().BindUObject(this, &AYourGameBackend::OnPurchaseItemResponse); Request->ProcessRequest(); } Godot Godot GDScript (Server-Side Logic) # This function MUST be on your secure server. # Assumes you have an HTTPRequest node named 'http_request'. # You can use OS.execute("uuidgen") on supported platforms or other methods for unique IDs. func purchase_item(player_email: String, item_id: String, quantity: int, price: float): var url = "https://invo.network/api/item-purchases/purchase-item" var headers = [ "X-Game-Secret-Key: your_game_secret_key_here", "Content-Type: application/json" ] var body = { "client_request_id": UUID.new().uuid_string(), # Requires a UUID plugin or custom function "player_email": player_email, "player_name": "Player From DB", "item_id": item_id, "item_name": "Item From DB", "item_quantity": quantity, "unit_price": "%.2f" % price, "total_price": "%.2f" % (price * quantity) } http_request.request(url, headers, HTTPClient.METHOD_POST, JSON.stringify(body)) 4. Helper Endpoints GET /api/item-purchases/player-purchase-history Retrieves a paginated list of items a player has purchased. Query Parameters: ?player_email=player@example.com&limit=25&offset=0 Example Response: { "player": { /* player details */ }, "item_purchase_history": [ { "transaction_id": "txn_...", "status": "completed", "amount": "150.00", "created_at": "2024-06-21T14:30:00Z", "item_id": "legendary_sword_001", "item_name": "Legendary Sword", "item_quantity": 1 } ], "pagination": { "total_count": 1, "limit": 25, "offset": 0, "has_more": false } } GET /api/item-purchases/order-details Retrieves the complete financial record for a single purchase order. Query Parameters: ?order_id=ord_... OR ?transaction_id=txn_... Example Response: { "order": { /* ... full order object ... */ }, "financial_summary": { "game_currency_spent": "150.00", "payment_method": "in_game_currency" }, "status_timeline": { "created_at": "2024-06-21T14:30:00Z", "completed_at": "2024-06-21T14:30:00Z" } } 5. Advanced Security Features Automated Fraud & Spam Protection The API includes several automated security checks to protect your game's economy from abuse. If a player triggers one of these checks, they will receive a 429 Too Many Requests error with a message explaining the block. Insufficient-balance lockout: 50 failed purchase attempts due to insufficient funds within 5 minutes triggers a 5-minute cooldown. Rapid-same-item lockout: More than 10 purchase attempts for the same item within 1 minute triggers a temporary block. Per-player spam lockout: Roughly 100 purchase attempts within a rolling 5-minute window triggers a cooldown (a secondary guard adds a wider 200-attempt limit). Expect to be told to retry in up to 15 minutes. Invalid-item lockout: 30 attempts referencing an unrecognized item within the window triggers a 10-minute cooldown. Malformed-request lockout: 50 invalid requests from the same network triggers a 30-minute cooldown. All 429 responses include a retry_after field (seconds) — back off accordingly.

---

## Platform Commerce API

URL: https://docs.invo.network/docs/platform-commerce
Endpoint: POST /api/platform-commerce/purchase

Sell items on your platform through Invo with dual funding: a user's Invo-network balance or a direct card payment. Server-side funding resolution, refunds, and webhooks.

Platform Commerce Sell items on your platform through Invo, with two ways to pay: a user's existing Invo-network balance, or a direct card payment on Invo's hosted checkout. Funding is resolved on your server, so network value always moves through Invo — never around it. Who this is for: platform tenants (non-game apps — content platforms, creator stores, marketplaces). Every endpoint below is available only to platform-tagged accounts; a standard game account receives 403 . For in-game item spending on a game account, use the Item Purchase API instead. Two funding legs Balance The user spends Invo-network currency they already hold. A ledger debit — no card, settles synchronously (the response is the completed sale). Amount is in your currency units. Invo fee: 3.5% flat . funding_source: "balance" Card A direct card payment (USD) on Invo's hosted checkout — card, Apple Pay, Google Pay, 3-D Secure, and international billing address all handled by us. Settles asynchronously on a verified webhook. Invo fee: 3.5% + $0.30 . funding_source: "card" Authentication All Platform Commerce endpoints are called from your server with your secret key: X-Game-Secret-Key: your_secret_key_here Never call these from a client, and never ship the secret key in a browser or app bundle. Funding is resolved server-side; for the card leg the browser only ever receives a single-use checkout_url . 1. Create a purchase POST /api/platform-commerce/purchase Request body Field Type Req. Notes client_request_id string yes Your idempotency key. A repeat with the same id is de-duplicated. funding_source string yes "balance" or "card" . Validated + enforced server-side. player_email string yes The buyer's email. player_name string yes ≤ 255 chars. item_id string yes Your item identifier. ≤ 255 chars. item_name string yes Shown to the buyer on the card checkout. ≤ 255 chars. item_quantity int yes 1–1000. unit_price decimal yes Rounded to 2 dp. total_price decimal yes Must equal unit_price × quantity . Card: USD, $0.50–$999.99. Balance: your currency units. item_description , item_category string no item_category ≤ 100 chars. player_phone string no Optional. success_url , cancel_url string no Card only — where to send the buyer after checkout. metadata object no Card only — your correlation data, echoed back to you. Note: the card leg does not take a billing address — the buyer enters it on Invo's hosted checkout and we capture it from the confirmed payment. Balance response — settled ( 200 ) { "status": "success", "funding_source": "balance", "order_id": 123, "transaction_id": "TXN_...", "new_balance": "45.00", "previous_balance": "50.00", "currency_name": "Gems", "financial_breakdown": { "total_paid": "5.00", "developer_revenue": "4.82", "platform_fee": "0.18" } } Card response — send the buyer to checkout ( 200 ) { "status": "requires_payment", "funding_source": "card", "session_id": "<id>", "checkout_url": "https://invo.network/checkout?session=<token>", "expires_at": 1690000000, "amount_usd": "5.00" } Card leg: send the buyer to the hosted checkout A card purchase is not paid when this returns — the order does not exist yet. Send the buyer to checkout_url ; they pay on Invo's hosted page. Treat the sale as final only when you receive the platform_commerce.purchased webhook. The link expires at expires_at (15 minutes). 2. The card checkout flow Your server calls POST /purchase with funding_source: "card" and gets a checkout_url . Send the buyer to it — either redirect ( window.location = checkout_url ) or embed it in an iframe. The buyer enters card + billing address on Invo's hosted checkout (card / Apple Pay / Google Pay / 3-D Secure) and pays. Invo verifies the payment, records the sale + fee, captures the billing address, and fires platform_commerce.purchased . The buyer is returned to your success_url (or cancel_url ). Fulfil the item on the webhook , not on the browser return. Embedding (optional) If you iframe the checkout, listen for the completion message from Invo's page: window.addEventListener('message', (e) => { if (e.data && e.data.type === 'INVO_CHECKOUT_COMPLETE') { // e.data.data.status === 'completed' // Show a confirmation UI — but still fulfil on the webhook. } }); 3. Check status GET /api/platform-commerce/purchase-status/{order_id} Poll an order (useful as a fallback to the webhook for card purchases). Returns: { "order_id": 123, "status": "completed", // completed | pending_payment | refunded "game_currency_amount": "5.00", // balance leg "usd_amount": "5.00", // card leg "payment_method": "card", // card | network_currency "created_at": "2026-07-20T..." } 4. Refund POST /api/platform-commerce/refund Refund a completed purchase. Body: { "order_id": 123 } or { "client_request_id": "..." } , plus optional reason . { "status": "refunded", "funding_source": "card", // or "balance" "order_id": 123, "transaction_id": "TXN_...", "refunded_amount_usd": "5.00", // card; balance -> "refunded_amount" + "new_balance" "stripe_refund_id": "...", // card only "fee_retained": true } The customer is made whole — a balance purchase re-credits the wallet, a card purchase refunds the card. Invo retains its fee on refunds ( fee_retained: true ). Only a completed order is refundable; a second refund on the same order returns 409 . Error codes HTTP Code Meaning 400 — Validation (missing/invalid field, price mismatch, bad email). 400 AMOUNT_BELOW_MINIMUM Fee rounds to zero — amount too small. 400 BELOW_STRIPE_MINIMUM Card total below $0.50. 400 ABOVE_CARD_MAXIMUM Card total above $999.99. 401 — Missing or invalid secret key. 403 NOT_A_PLATFORM_TENANT This API is for platform tenants only. 409 — Duplicate client_request_id / order already refunded. 429 — Rate limited. 503 service_unavailable Temporarily unavailable — retry shortly. Webhooks Subscribe (see Webhook Management ). Card purchases must be fulfilled here — this is the source of truth, not the browser return. platform_commerce.purchased { "event": "platform_commerce.purchased", "data": { "transaction_id": "TXN_...", "order_id": 123, "funding_source": "card", // or "balance" "player_email": "buyer@example.com", "identity_id": "...", "item_id": "sticker_pack_01", "item_name": "Sticker Pack", "item_quantity": 1, "total_price_usd": "5.00", // card; balance -> "total_price" + "currency_name" + "new_balance" "client_request_id": "...", // card "fee_breakdown": { "total_paid": "5.00", "platform_fee": "0.30", "developer_revenue": "4.70" } } } platform_commerce.refunded { "event": "platform_commerce.refunded", "data": { "order_id": 123, "funding_source": "card", "player_email": "buyer@example.com", "identity_id": "...", "refunded_amount": "5.00", "amount_unit": "usd", // "usd" (card) or "currency" (balance) "fee_retained": true } } Idempotency. Always send a stable client_request_id . Balance: a repeat returns 409 (already processed). Card: a repeat returns the same checkout session ( idempotent_replay: true ) so a retry can't create a second charge. Fees. Balance leg: 3.5% flat. Card leg: 3.5% + $0.30. Your revenue on each sale is the total minus the Invo fee, returned in financial_breakdown (balance response) and on the purchase webhook ( fee_breakdown ).

---

## Payment Methods

URL: https://docs.invo.network/docs/payment-methods

Learn about supported payment methods for currency and item purchases in Invo Network.

Payment Methods INVO Network's hosted checkout system accepts all major payment methods worldwide. No integration complexity - we handle everything. One Integration, All Payment Methods Our hosted checkout automatically supports all major payment methods. No additional code, no extra integrations - it just works. Credit & Debit Cards ✓ Visa ✓ Mastercard ✓ American Express ✓ Discover ✓ JCB ✓ Diners Club Global Support ✓ 135+ currencies ✓ 195+ countries ✓ Local payment methods ✓ Multi-language support ✓ Regional compliance ✓ Currency conversion Security Features ✓ 3D Secure (3DS2) ✓ PCI DSS Level 1 ✓ Fraud detection ✓ Risk scoring ✓ Encrypted storage ✓ Secure tokenization Advanced Features Included Saved Cards Players can securely save their payment methods for faster checkout on future purchases. We handle all tokenization and PCI compliance. • Fast repeat purchases with confirmation • Secure card tokenization • Player can manage saved cards • Automatic card updates 3D Secure Authentication Built-in support for 3D Secure 2.0 provides enhanced security and reduces fraud while improving approval rates. • Automatic bank verification • Biometric authentication • Reduced chargebacks • SCA compliance (Europe) Mobile Optimized Checkout experience is fully optimized for mobile devices with responsive design and native mobile wallet support. • Apple Pay ready • Google Pay ready • Touch-friendly interface • Auto-fill card details Smart Retries Automatic retry logic for declined payments maximizes successful transactions without any additional work from you. • Intelligent decline handling • Network retry optimization • Soft decline recovery • Higher approval rates Regional Payment Methods INVO Network automatically enables popular regional payment methods based on the player's location: 🇪🇺 Europe • SEPA Direct Debit • iDEAL (Netherlands) • Bancontact (Belgium) • Sofort (Germany) • Giropay (Germany) 🌏 Asia Pacific • Alipay (China) • WeChat Pay (China) • GrabPay (Southeast Asia) • PayNow (Singapore) • FPX (Malaysia) 🌎 Americas • ACH Direct Debit (US) • OXXO (Mexico) • Boleto (Brazil) • PIX (Brazil) • Interac (Canada) Automatic Activation: Regional methods appear automatically for eligible players - no configuration required. Which purchase call do I use? Pick your integration by where your product lives. You never choose a payment processor yourself — just set the rail on your purchase request and we route it to the right methods automatically. Your product rail What you get A platform or non-game app (web / mobile storefront, creator platform) "platform" Cards + regional methods worldwide. This is the default if you omit rail . A game distributed anywhere except Steam (mobile, standalone, web, console store) "game" Broad global & regional payment methods tuned for games. A game distributed on Steam "steam" Players pay with their Steam Wallet (required for Steam titles). Use the in-client flow in the Steam purchase guide. How to set it: add "rail": "game" (or "platform" / "steam" ) to your purchase request body. Omit it and you get "platform" . Every webhook you receive echoes the rail back, so you always know which path a purchase took. Why Our Payment System Matters For Your Players ✓ Fast Checkout: Most transactions complete in under 30 seconds ✓ Trusted Security: Bank-level encryption visible in the checkout UI ✓ Their Preferred Method: Multiple payment options increase conversion For Your Business ✓ Higher Conversion: More payment methods = more completed purchases ✓ Lower Fraud: AI-powered fraud detection protects your revenue ✓ Zero Maintenance: We handle updates, compliance, and new methods Ready to Accept Payments? Get started with INVO Network's hosted checkout. One integration gives you access to all payment methods worldwide. View Integration Guide Register Your Game Full integration in under 1 hour • No PCI compliance required • Enterprise support included

---

## Transfer Overview

URL: https://docs.invo.network/docs/transfer-overview

Overview of cross-game transfer functionality and how players can move value between games.

Cross-Game Transfers Overview Enable secure, verified transfers of in-game currency between different games in your ecosystem. Our transfer system uses SMS verification and claim codes to ensure only authorized transfers are completed. Steam-purchased currency stays within Steam titles Currency a player buys through Steam can move among Steam-distributed games but not to non-Steam games, and non-Steam currency can't move into Steam titles. This containment is configured per-title by the platform and does not affect games that aren't Steam-distributed. When it applies, non-Steam destinations are omitted from destination lists for Steam-purchased balances, and an over-limit or wrong-direction move is rejected with a STEAM_VALUE_NON_TRANSFERABLE or NON_STEAM_VALUE_INTO_STEAM_BLOCKED 409. Integration Flow for Game Developers Step 1: Get Available Destinations (Cache Daily) Before building your transfer UI, fetch the list of games your players can transfer to. This data should be cached locally and refreshed once per day. POST /api/transfers/available-destinations • Cache Duration: 24 hours (games don't change frequently) • Refresh Trigger: Daily app startup or manual refresh • Storage: Local file, localStorage, or in-memory cache • Performance: Prevents API calls every time player opens transfer UI 2 Build Transfer UI Use the cached destination data to create your transfer interface. Show game names, icons, currency types, and transfer limits. UI Elements: Game selection dropdown, currency display, amount input with min/max validation, fee preview. 3 Process Transfer When player confirms transfer, call the initiate → verify → claim sequence using the existing transfer APIs. API Sequence: /initiate-transfer → /verify-sms → /claim-transfer (recipient's game) Note: handle HTTP 202. If the initiating account is flagged as a minor on Invo, /initiate-transfer returns 202 pending_guardian_approval with a polling endpoint. Adult accounts are unaffected. See Guardian Approval . Available Destinations API POST /api/transfers/available-destinations Get games that players can transfer currency to Request Body { "source_game_id": "123456789012" } Headers X-Game-Secret-Key: your_secret_key Content-Type: application/json Sample Response { "status": "success", "source_game_id": "123456789012", "source_game_name": "Adventure Quest", "source_game_icon": "https://cdn.example.com/aq_icon.png", "source_currency_name": "Gold", "source_currency_icon": "https://cdn.example.com/gold_symbol.png", "universal_transfers": "yes", "transfer_mode": "universal", "available_games": [ { "game_id": "987654321098", "game_name": "Space Warriors", "tenant_type": "game", "developer_name": "Stellar Studios", "publisher_name": "Stellar Publishing", "genre": "Action", "platform": "PC", "game_status": "live", "game_icon": "https://cdn.example.com/space_icon.png", "game_poster": "https://cdn.example.com/space_poster.png", "game_url": "https://stellarstudios.com/space-warriors", "game_description": "Fast-paced space combat.", "currency_name": "Energy Credits", "currency_symbol": "EC", "currency_symbol_url": "https://cdn.example.com/ec_symbol.png", "minimum_transfer": "5.00", "maximum_transfer": "1000.00", "accepts_steam_origin_value": true }, { "game_id": "111222333444", "game_name": "Fantasy Kingdom", "tenant_type": "game", "developer_name": "Magic Games", "publisher_name": "Magic Publishing", "genre": "RPG", "platform": "Mobile", "game_status": "live", "game_icon": "https://cdn.example.com/fantasy_icon.png", "game_poster": "https://cdn.example.com/fantasy_poster.png", "game_url": "https://magicgames.com/fantasy-kingdom", "game_description": "Epic fantasy adventure.", "currency_name": "Gold Coins", "currency_symbol": "GC", "currency_symbol_url": "https://cdn.example.com/gc_symbol.png", "minimum_transfer": "1.00", "maximum_transfer": null, "accepts_steam_origin_value": false } ], "total_destinations": 2 } // accepts_steam_origin_value: true only for Steam-distributed titles. // When the source game is not a Steam title, Steam-distributed // destinations are omitted from available_games entirely. // // In linked mode (universal_transfers: "no") the response also includes: // "linked_game_ids": ["987654321098", "111222333444"] Transfer Mode Logic Universal Transfers When your game has universal_transfers = "yes" • Players can transfer to ALL live games • No configuration needed • Maximum ecosystem connectivity • Excludes testing/inactive games Linked Transfers When your game has universal_transfers = "no" • Players can transfer ONLY to linked games • Uses your game's linked_game_ids field • Controlled partnerships • Curated transfer destinations Caching Implementation Guide Why Cache This API? • Performance: Instant transfer UI loading • Reliability: Works even if API is temporarily unavailable • Cost: Reduces API calls (game list doesn't change often) • User Experience: No loading delays when opening transfer screen Unity Unity C# Caching Implementation // Cache destination games data public class TransferDestinationsCache : MonoBehaviour { private const string CACHE_KEY = "transfer_destinations"; private const string CACHE_TIME_KEY = "destinations_cached_at"; private const int CACHE_DURATION_HOURS = 24; [System.Serializable] public class DestinationsData { public string status; public string source_game_name; public string universal_transfers; public GameDestination[] available_games; public int total_destinations; } public void CacheDestinations(DestinationsData data) { string json = JsonUtility.ToJson(data); PlayerPrefs.SetString(CACHE_KEY, json); PlayerPrefs.SetString(CACHE_TIME_KEY, System.DateTime.Now.ToBinary().ToString()); PlayerPrefs.Save(); Debug.Log($"Cached {data.total_destinations} transfer destinations"); } public DestinationsData GetCachedDestinations() { if (!PlayerPrefs.HasKey(CACHE_KEY)) return null; // Check if cache is expired if (IsCacheExpired()) { Debug.Log("Destinations cache expired, refreshing..."); RefreshDestinations(); return null; } string json = PlayerPrefs.GetString(CACHE_KEY); return JsonUtility.FromJson<DestinationsData>(json); } private bool IsCacheExpired() { if (!PlayerPrefs.HasKey(CACHE_TIME_KEY)) return true; long cacheTicks = System.Convert.ToInt64(PlayerPrefs.GetString(CACHE_TIME_KEY)); System.DateTime cacheTime = System.DateTime.FromBinary(cacheTicks); return (System.DateTime.Now - cacheTime).TotalHours > CACHE_DURATION_HOURS; } public void RefreshDestinations() { StartCoroutine(FetchDestinationsFromAPI()); } private IEnumerator FetchDestinationsFromAPI() { // Call the available-destinations API here // Cache the result using CacheDestinations() } } Web JavaScript/Web Caching Implementation class TransferDestinationsCache { constructor() { this.CACHE_KEY = 'invo_transfer_destinations'; this.CACHE_TIME_KEY = 'invo_destinations_cached_at'; this.CACHE_DURATION_HOURS = 24; } async getDestinations(gameId, secretKey) { // Try to get from cache first const cached = this.getCachedDestinations(); if (cached) { console.log('Using cached transfer destinations'); return cached; } // Cache miss or expired, fetch from API console.log('Fetching fresh transfer destinations...'); return await this.fetchAndCacheDestinations(gameId, secretKey); } getCachedDestinations() { const cachedData = localStorage.getItem(this.CACHE_KEY); const cacheTime = localStorage.getItem(this.CACHE_TIME_KEY); if (!cachedData || !cacheTime) return null; // Check if expired const now = new Date().getTime(); const cached = new Date(parseInt(cacheTime)).getTime(); const hoursOld = (now - cached) / (1000 * 60 * 60); if (hoursOld > this.CACHE_DURATION_HOURS) { console.log('Cache expired, need fresh data'); return null; } return JSON.parse(cachedData); } async fetchAndCacheDestinations(gameId, secretKey) { try { const response = await fetch('/api/transfers/available-destinations', { method: 'POST', headers: { 'X-Game-Secret-Key': secretKey, 'Content-Type': 'application/json' }, body: JSON.stringify({ source_game_id: gameId }) }); const data = await response.json(); if (data.status === 'success') { // Cache the successful response localStorage.setItem(this.CACHE_KEY, JSON.stringify(data)); localStorage.setItem(this.CACHE_TIME_KEY, new Date().getTime().toString()); console.log(`Cached ${data.total_destinations} destinations`); } return data; } catch (error) { console.error('Failed to fetch destinations:', error); throw error; } } clearCache() { localStorage.removeItem(this.CACHE_KEY); localStorage.removeItem(this.CACHE_TIME_KEY); } } // Usage example const cache = new TransferDestinationsCache(); const destinations = await cache.getDestinations('123456789012', 'your_secret_key'); Transfer Process 4 Steps Get Destinations → Initiate → Verify → Claim Security SMS + PIN Two-factor verification Transfer Fee 10% 3.5% source + 3.5% target + 3% network Cache Duration 24 Hours Destinations API cache How Cross-Game Transfers Work 0 Get Available Destinations (Daily) Before showing transfer options, your game calls the destinations API to get the current list of games players can transfer to. This data is cached locally for 24 hours for performance. What happens: API returns game list based on universal_transfers setting, data cached locally, transfer UI populated. 1 Initiate Transfer Player selects destination game from cached list, enters target recipient phone, amount, and confirms transfer. The system validates the transfer, calculates fees, and reserves the amount from their balance. 🔒 The claim code is locked to the target phone. What happens: Amount is reserved, claim code locked to target phone, SMS PIN generated and sent, transfer enters "pending verification" status. 2 SMS Verification Player receives an SMS with a verification PIN (valid for 10 minutes). They enter this PIN in the source game to confirm they authorized the transfer. This prevents unauthorized transfers. What happens: PIN is verified, claim code is generated and sent via SMS, transfer enters "pending claim" status. 3 Claim Transfer Recipient uses the claim code in the target game to receive the transferred currency. 🔒 The claim code can ONLY be redeemed by the exact phone number specified during initiation. Valid for 24 hours, one-time use only. What happens: Phone number verified, currency credited to recipient's balance, transfer completed, confirmation SMS sent. Detecting verification completion After /initiate-transfer , the sender still has to clear verification (enter the SMS PIN, or approve in-app) before the transfer moves to pending_claim . Your server can poll this endpoint to drive a "waiting" panel and know the moment verification lands. GET /api/transfers/ {id} /status Poll the verification state of a transfer (server-side) • Auth: X-Game-Secret-Key — server-side only. Scoped to your game: callable whether you are the source or the target game on the transfer. • Rate limit: 60 requests per minute per IP. • Returns: transaction_status (the raw transaction status) and verification_state (a normalized waiting-panel state). verification_state values verification_state Meaning awaiting Verification not yet cleared. Keep the waiting panel up and keep polling. approved Sender cleared verification (SMS PIN or in-app). Flips from awaiting the moment this happens — stop showing the verification UI. completed Transfer fully claimed and credited. expired Verification or claim window lapsed. Funds returned to sender. failed Verification failed or the transfer was cancelled. Funds returned to sender. The verification_method returned by /initiate-transfer determines which screen the user sees while you poll: the SMS PIN screen when it is 'sms' , or the in-app approval panel when it is 'in_app' . In both cases the waiting panel polls this endpoint and dismisses when verification_state flips to approved . GET /api/transfers/txn_abc123def456/status X-Game-Secret-Key: your_game_secret_key_here // 200 OK { "status": "success", "transaction_status": "pending_claim", "verification_state": "approved" } Fee Structure Default split (both tenants at 3.5%) Source tenant fee 3.5% Target tenant fee 3.5% Network fee (Invo) 3.0% Total user-paid fee 10.0% Example transfer Transfer amount: 1,000 Gold Total fees (10%): -100 Gold Recipient receives: 900 Gold Per-tenant rate overrides Each tenant has a transfer_fee_percentage field (default 3.5% , range 0–10) that controls its own kickback share on every transfer/send it participates in. Negotiated rates above the default come out of Invo's 3% slice — not the other side's. The user-paid total stays at exactly 10%. Example: source tenant overridden to 5%, target at default 3.5% Source 5.0% Target 3.5% Invo 1.5% Invo's slice absorbs the +1.5% above source's default. Both override sides combined cannot exceed 10% — at runtime, side fees scale down proportionally if they would otherwise push Invo below 0. Always read fee_breakdown from the API response and fee_total from the webhook payload — those reflect the actual numbers applied to that specific transfer. Do not recompute fees client-side. Rate Limits & Restrictions Current Limits (Launch Period) Destinations API • 100 requests per minute per IP • Should be cached for 24 hours • Call once daily at app startup Per Player Limits • 100 transfer initiations per hour • 40 SMS verifications per hour • 30 claim attempts per hour • 10 transfers per hour (velocity limit) • Daily amount: configurable per-game limit (default 1,000,000 currency units, adjustable by the platform) Per IP Address Limits • 300 initiations per hour • 200 verifications per hour • 150 claims per hour • 20 requests per minute Note: These limits are generous during the initial launch period and may be adjusted based on usage patterns and security requirements. Integration Best Practices Caching Strategy • Call /available-destinations once per day, cache locally • Use cached data to build transfer UI instantly • Refresh cache on app startup or manual refresh • Store in persistent storage (not just memory) • Handle cache miss gracefully with loading states User Experience • Show game icons and names from destinations data • Display currency symbols and names clearly • Validate transfer amounts against min/max limits • Preview fees before confirming transfer • Provide clear error messages for validation failures Performance • Never call destinations API when player opens transfer UI • Use background refresh to update cache silently • Implement proper error handling for API failures • Show fallback UI if destinations data unavailable • Consider CDN for game icons/assets Error Handling • Handle "no destinations available" gracefully • Show appropriate messages for universal vs linked modes • Retry failed destination requests with backoff • Log destination API failures for debugging • Provide manual refresh option for users Security & Anti-Fraud Features 🔒 Phone-Based Claim Security Transfer claim codes are now locked to specific phone numbers. Only the target phone specified during initiation can redeem the claim code. • target_player_phone required at initiation • Claim codes can ONLY be redeemed by the specified phone number • Phone mismatch results in 403 Forbidden error • Prevents unauthorized claim code sharing and redemption SMS Verification • SMS PIN required to authorize transfers • 10-minute expiration window • Maximum 3 attempts per PIN • Rate limiting on SMS requests • Phone-locked claim codes Fraud Prevention • Transfer velocity limits per player • Duplicate transfer detection • IP-based rate limiting • Failed attempt tracking and blocking Time Limits • SMS PIN: 10 minutes to verify • Claim code: 24 hours to claim • Expired transfers return funds automatically • No funds lost due to expiration Player Protection • Funds reserved during verification • Automatic refunds on failure/expiration • Clear status tracking throughout process • SMS notifications at each step Transfer Status Definitions pending_pin_verification Transfer initiated, waiting for SMS PIN verification. Funds are reserved. pending_claim SMS verified, claim code sent. Waiting for recipient to claim the transfer. completed Transfer successfully claimed and completed. Currency credited to recipient. failed / expired Transfer failed verification, expired, or was cancelled. Funds returned to sender.

---

## Available Destinations

URL: https://docs.invo.network/docs/available-destinations
Endpoint: POST /api/transfers/available-destinations

API documentation for retrieving available destination games for player transfers.

Available Transfer Destinations API Get the list of games that players can transfer currency to from your game. This endpoint should be called once daily and cached locally for optimal performance. Performance Critical - Cache This Response! ✅ DO THIS • Call this API once per day • Cache response locally for 24 hours • Use cached data to build transfer UI • Refresh on app startup or manual refresh ❌ DON'T DO THIS • Call this API every time player opens transfer UI • Make requests during gameplay • Skip caching for "real-time" data • Store response only in memory POST /api/transfers/available-destinations Get games that accept transfers from your game Authentication Required All requests must include your game's secret key in the request headers: X-Game-Secret-Key: your_game_secret_key_here Request Body Parameters Parameter Type Required Description source_game_id string Yes Your game's ID (must match authenticated game) Transfer Logic Modes Universal Transfers universal_transfers = "yes" • Returns: ALL live games that accept incoming transfers • Excludes: Your own game, testing games, inactive games • Best for: Maximum ecosystem connectivity • Configuration: Set in your game's database record Linked Transfers universal_transfers = "no" • Returns: ONLY games in your linked_game_ids field • Excludes: Testing games, inactive games • Best for: Curated partnerships, controlled ecosystem • Configuration: Manage linked_game_ids array in database Request Example POST /api/transfers/available-destinations Content-Type: application/json X-Game-Secret-Key: your_game_secret_key_here { "source_game_id": "123456789012" } Response Examples Universal Transfers - Success Response (200 OK) { "status": "success", "source_game_id": "123456789012", "source_game_name": "Adventure Quest", "universal_transfers": "yes", "transfer_mode": "universal", "available_games": [ { "game_id": "987654321098", "game_name": "Space Warriors", "developer_name": "Stellar Studios", "publisher_name": "Galaxy Entertainment", "genre": "Action", "platform": "Mobile", "game_status": "live", "game_icon": "https://cdn.invo.network/games/space_icon.png", "game_poster": "https://cdn.invo.network/games/space_poster.jpg", "game_url": "https://spacewarriors.com", "game_description": "Epic space combat game", "currency_name": "Energy Credits", "currency_symbol": "EC", "currency_symbol_url": "https://cdn.invo.network/currencies/ec_icon.png", "minimum_transfer": "5.00", "maximum_transfer": "1000.00", "accepts_steam_origin_value": true }, { "game_id": "111222333444", "game_name": "Fantasy Kingdom", "developer_name": "Magic Studios", "publisher_name": null, "genre": "RPG", "platform": "Web", "game_status": "live", "game_icon": "https://cdn.invo.network/games/fantasy_icon.png", "game_poster": null, "game_url": "https://fantasykingdom.com", "game_description": "Build your magical empire", "currency_name": "Gold Coins", "currency_symbol": "GC", "currency_symbol_url": null, "minimum_transfer": "1.00", "maximum_transfer": null, "accepts_steam_origin_value": false } ], "total_destinations": 2 } Linked Transfers - Success Response (200 OK) { "status": "success", "source_game_id": "123456789012", "source_game_name": "Adventure Quest", "universal_transfers": "no", "transfer_mode": "linked", "linked_game_ids": ["987654321098", "555666777888"], "available_games": [ { "game_id": "987654321098", "game_name": "Space Warriors", "developer_name": "Stellar Studios", "publisher_name": "Galaxy Entertainment", "genre": "Action", "platform": "Mobile", "game_status": "live", "game_icon": "https://cdn.invo.network/games/space_icon.png", "game_poster": "https://cdn.invo.network/games/space_poster.jpg", "game_url": "https://spacewarriors.com", "game_description": "Epic space combat game", "currency_name": "Energy Credits", "currency_symbol": "EC", "currency_symbol_url": "https://cdn.invo.network/currencies/ec_icon.png", "minimum_transfer": "5.00", "maximum_transfer": "1000.00", "accepts_steam_origin_value": true } ], "total_destinations": 1 } No Destinations Available (200 OK) { "status": "success", "source_game_id": "123456789012", "source_game_name": "Adventure Quest", "universal_transfers": "no", "transfer_mode": "linked", "linked_game_ids": [], "available_games": [], "total_destinations": 0, "message": "No linked games configured for transfers" } Error Response - Outgoing Transfers Disabled (403 Forbidden) { "status": "error", "message": "Source game does not allow outgoing transfers" } Steam-distributed destinations & accepts_steam_origin_value • Each destination includes accepts_steam_origin_value — true when the destination is a Steam-distributed title that can receive Steam-purchased currency. Use it to gray out or disable non-Steam destinations for a player who holds Steam-purchased currency. • When the source game is not a Steam title, Steam-distributed destinations are omitted from the list entirely — non-Steam currency can't enter Steam titles, so they are never valid targets. • This only matters for ecosystems that include Steam-distributed titles (a per-title platform setting); most integrations see every destination with accepts_steam_origin_value: false . Implementation Examples Unity Unity C# Available Destinations with Caching // This function should be called once daily and cached public IEnumerator GetAvailableDestinations(string sourceGameId, Action<string> onSuccess, Action<string> onError) { string url = "https://invo.network/api/transfers/available-destinations"; var requestData = new { source_game_id = sourceGameId }; string jsonBody = JsonUtility.ToJson(requestData); using (UnityWebRequest request = new UnityWebRequest(url, "POST")) { byte[] bodyRaw = System.Text.Encoding.UTF8.GetBytes(jsonBody); request.uploadHandler = new UploadHandlerRaw(bodyRaw); request.downloadHandler = new DownloadHandlerBuffer(); request.SetRequestHeader("X-Game-Secret-Key", "your_game_secret_key_here"); request.SetRequestHeader("Content-Type", "application/json"); yield return request.SendWebRequest(); if (request.result == UnityWebRequest.Result.Success) { // Cache this response for 24 hours CacheDestinationsResponse(request.downloadHandler.text); onSuccess?.Invoke(request.downloadHandler.text); } else { onError?.Invoke(request.error + ": " + request.downloadHandler.text); } } } private void CacheDestinationsResponse(string jsonResponse) { PlayerPrefs.SetString("cached_destinations", jsonResponse); PlayerPrefs.SetString("destinations_cache_time", System.DateTime.Now.ToBinary().ToString()); PlayerPrefs.Save(); Debug.Log("Destinations cached for 24 hours"); } public string GetCachedDestinations() { if (!PlayerPrefs.HasKey("cached_destinations")) return null; // Check if cache is expired (24 hours) string cacheTimeStr = PlayerPrefs.GetString("destinations_cache_time"); if (!string.IsNullOrEmpty(cacheTimeStr)) { long cacheTicks = System.Convert.ToInt64(cacheTimeStr); System.DateTime cacheTime = System.DateTime.FromBinary(cacheTicks); if ((System.DateTime.Now - cacheTime).TotalHours > 24) { // Cache expired return null; } } return PlayerPrefs.GetString("cached_destinations"); } Unreal Unreal C++ Available Destinations with Caching // This function should be called once daily and cached void AYourGameMode::GetAvailableDestinations(const FString& SourceGameId) { TSharedPtr<FJsonObject> RequestObj = MakeShareable(new FJsonObject); RequestObj->SetStringField("source_game_id", SourceGameId); FString RequestBody; TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&RequestBody); FJsonSerializer::Serialize(RequestObj.ToSharedRef(), Writer); TSharedRef<IHttpRequest> Request = FHttpModule::Get().CreateRequest(); Request->SetURL("https://invo.network/api/transfers/available-destinations"); Request->SetVerb("POST"); Request->SetHeader("X-Game-Secret-Key", "your_game_secret_key_here"); Request->SetHeader("Content-Type", "application/json"); Request->SetContentAsString(RequestBody); Request->OnProcessRequestComplete().BindUObject(this, &AYourGameMode::OnDestinationsReceived); Request->ProcessRequest(); } void AYourGameMode::OnDestinationsReceived(FHttpRequestPtr Request, FHttpResponsePtr Response, bool bWasSuccessful) { if (bWasSuccessful && Response.IsValid()) { FString ResponseContent = Response->GetContentAsString(); if (Response->GetResponseCode() == 200) { // Cache the response for 24 hours CacheDestinationsResponse(ResponseContent); // Process the destinations data ProcessDestinationsResponse(ResponseContent); } else { UE_LOG(LogTemp, Error, TEXT("Failed to get destinations: %s"), *ResponseContent); } } else { UE_LOG(LogTemp, Error, TEXT("HTTP request failed")); } } void AYourGameMode::CacheDestinationsResponse(const FString& JsonResponse) { // Save to game instance or persistent storage if (UGameInstanceSubsystem* GameInstance = GetGameInstance()->GetSubsystem<UGameInstanceSubsystem>()) { GameInstance->SetCachedDestinations(JsonResponse); GameInstance->SetDestinationsCacheTime(FDateTime::Now()); UE_LOG(LogTemp, Log, TEXT("Destinations cached for 24 hours")); } } FString AYourGameMode::GetCachedDestinations() { if (UGameInstanceSubsystem* GameInstance = GetGameInstance()->GetSubsystem<UGameInstanceSubsystem>()) { FDateTime CacheTime = GameInstance->GetDestinationsCacheTime(); FDateTime Now = FDateTime::Now(); // Check if cache is expired (24 hours) if ((Now - CacheTime).GetTotalHours() > 24.0) { return FString(); // Cache expired } return GameInstance->GetCachedDestinations(); } return FString(); } Godot Godot GDScript Available Destinations with Caching # This function should be called once daily and cached func get_available_destinations(source_game_id: String): var url = "https://invo.network/api/transfers/available-destinations" var headers = [ "X-Game-Secret-Key: your_game_secret_key_here", "Content-Type: application/json" ] var body = { "source_game_id": source_game_id } var http_request = HTTPRequest.new() add_child(http_request) http_request.request_completed.connect(_on_destinations_received) http_request.request(url, headers, HTTPClient.METHOD_POST, JSON.stringify(body)) func _on_destinations_received(result: int, response_code: int, headers: PackedStringArray, body: PackedByteArray): var json_string = body.get_string_from_utf8() if response_code == 200: # Cache the response for 24 hours cache_destinations_response(json_string) # Process the destinations data process_destinations_response(json_string) print("Destinations retrieved and cached successfully") else: print("Failed to get destinations: ", json_string) func cache_destinations_response(json_response: String): # Save to user data directory var file = FileAccess.open("user://cached_destinations.json", FileAccess.WRITE) if file: var cache_data = { "destinations": json_response, "cache_time": Time.get_unix_time_from_system() } file.store_string(JSON.stringify(cache_data)) file.close() print("Destinations cached for 24 hours") func get_cached_destinations() -> String: var file = FileAccess.open("user://cached_destinations.json", FileAccess.READ) if not file: return "" var cache_data_str = file.get_as_text() file.close() var json = JSON.new() var parse_result = json.parse(cache_data_str) if parse_result != OK: return "" var cache_data = json.data var cache_time = cache_data.get("cache_time", 0) var current_time = Time.get_unix_time_from_system() # Check if cache is expired (24 hours = 86400 seconds) if (current_time - cache_time) > 86400: print("Destinations cache expired") return "" return cache_data.get("destinations", "") func should_refresh_destinations() -> bool: var cached = get_cached_destinations() return cached.is_empty() # Call this on game startup func initialize_destinations(): if should_refresh_destinations(): print("Refreshing destinations from API") get_available_destinations("123456789012") # Your game ID else: print("Using cached destinations") var cached_data = get_cached_destinations() process_destinations_response(cached_data) func process_destinations_response(json_response: String): var json = JSON.new() var parse_result = json.parse(json_response) if parse_result != OK: print("Error parsing destinations response") return var data = json.data if data.get("status") == "success": var available_games = data.get("available_games", []) print("Available destinations: ", available_games.size()) # Build your transfer UI here using available_games data else: print("API error: ", data.get("message", "Unknown error")) Building Transfer UI from Response Data Response Data Usage Guide Field UI Usage Example game_name Primary display text "Space Warriors" game_icon Game thumbnail/logo 64x64px icon next to name currency_name Currency description "Energy Credits" currency_symbol Currency abbreviation "EC" next to amounts minimum_transfer Input validation Minimum value for amount field maximum_transfer Input validation Maximum value (null = no limit) developer_name Secondary info Small text under game name genre Filtering/categorization Group games by type accepts_steam_origin_value Enable/disable destination for players holding Steam-purchased currency true = Steam-distributed title (accepts Steam-purchased currency) Sample Transfer UI Layout Space Warriors by Stellar Studios • Action Energy Credits (EC) Min: 5.00 • Max: 1,000.00 Fantasy Kingdom by Magic Studios • RPG Gold Coins (GC) Min: 1.00 • No max Error Handling HTTP 400 - Bad Request • Missing source_game_id in request body • Invalid game ID format (not numeric) HTTP 404 - Not Found • Source game not found HTTP 403 - Forbidden • Invalid or missing X-Game-Secret-Key header • Authenticated game doesn't match source_game_id • Source game has outgoing transfers disabled HTTP 429 - Too Many Requests • IP address exceeded 100 requests per minute • Implement exponential backoff for retries • This shouldn't happen with proper daily caching HTTP 500 - Server Error • Database connectivity issues • Internal system errors • Retry with exponential backoff • Fall back to cached data if available Implementation Checklist Before Going Live API called once daily and response cached locally Cache stored in persistent storage (not just memory) Transfer UI built from cached data for instant loading Proper error handling for API failures Fallback UI shown when no destinations available Transfer amount validation uses min/max limits from response Game icons and branding displayed correctly Manual refresh option available for users Cache age indicator shown to users (optional) Tested with both universal and linked transfer modes

---

## Player-Aware Destinations

URL: https://docs.invo.network/docs/player-destinations
Endpoint: POST /api/players/destinations

API documentation for /api/players/destinations — returns the games where a specific player already has a presence, intersected with the source tenant's transfer policy. The recommended endpoint for transfer / send UIs.

Player-Aware Destinations API The right endpoint to power the destination dropdown in your transfer or send UI. Returns only the games where this specific player already has a presence — typically a much shorter list than every reachable game on the network. When to use this Player-Aware Destinations • You already know who the player is (signed in) • You're rendering a transfer / send wizard • You want a short, relevant list (places the user actually has a presence) • You want to show "you have X balance there" hints Available Destinations (the per-tenant endpoint) • You don't have a specific player yet (admin tools, onboarding) • You want every game your tenant could reach • You're building dashboards, not user-facing UI POST /api/players/destinations Resolve every reachable destination this player already has a presence on Authentication Authenticate as the source tenant (your tenant) — the same SDK key you use to initiate transfers and sends. X-Game-Secret-Key: ivsdk_your_secret_key Request Body Field Type Required Description email string Yes Player email. Lower-cased server-side. phone string Yes E.164 preferred ( +15551234567 ); common formats are also canonicalized. Both fields are required because the network-wide identity hash is computed from (email, phone) together. Email alone is not enough to disambiguate accounts that share an email address with a different phone (or vice versa). Example request curl -X POST https://invo.network/api/players/destinations \ -H "X-Game-Secret-Key: ivsdk_your_secret_key" \ -H "Content-Type: application/json" \ -d '{ "email": "player@example.com", "phone": "+15551234567" }' 200 response { "status": "success", "source_game_id": "337916575744", "source_game_name": "GTA-6", "transfer_mode": "universal", "destinations": [ { "game_id": "97288428282", "game_name": "AtheraPlay", "tenant_type": "video_platform", "game_status": "live", "default_currency": { "currency_id": 17, "currency_name": "Athero Stars", "currency_symbol": "*" }, "available_balance": "120.00", "last_active": "2026-04-29T13:10:09+00:00", "accepts_steam_origin_value": false } ] } • destinations is sorted by most-recent activity, then game name. • transfer_mode reflects your tenant's policy: universal returns every live tenant the player exists on; linked intersects with your linked_game_ids allowlist. • available_balance is in the destination's default currency. • accepts_steam_origin_value is true when the destination is a Steam-distributed title that can receive Steam-purchased currency. Use it to gray out non-Steam destinations for a player holding Steam-purchased currency. When your source tenant is not a Steam title, Steam-distributed destinations are omitted from destinations entirely (non-Steam currency can't enter Steam titles). This only applies to ecosystems with Steam-distributed titles. • An empty destinations array is a normal result (player exists only on your tenant). Surface as "no other tenants yet," not as an error. Errors HTTP When 400 Missing or invalid email / phone 401 Missing or invalid X-Game-Secret-Key 403 Source tenant has outgoing transfers disabled Privacy & leak model The caller is required to know (email, phone) for the player they're acting on — if they didn't, they couldn't initiate a transfer or send for that player anyway. The destinations we return are filtered to tenants that your tenant is already legally allowed to transfer to (per your universal_transfers / linked_game_ids policy). We never reveal a presence on a tenant the caller couldn't act against, so this endpoint is safe to surface in user-facing UI. Use it the same way for sends This single endpoint covers both self-transfer (player moves their own balance to a destination tenant) and player-to-player send (gift to another human). The destinations returned are valid for either flow — pick the matching game_id as target_game_id in your subsequent /initiate-transfer or /initiate-send call. For sends to a different human, run this lookup against the recipient's (email, phone) , not the sender's.

---

## Write-Response Contract

URL: https://docs.invo.network/docs/write-response-contract

Documentation for the canonical top-level new_balance field returned by every Invo write endpoint that affects a player balance — purchase, transfer, send, item-purchase. Type, units, when null, recommended dual-read pattern with GET /player-balances.

Write-Response Contract: new_balance Every Invo endpoint that credits or debits a player's balance returns the post-write balance at one canonical location: response.new_balance . Read from there. Why this exists Wallet UIs need to display the player's new balance immediately after every write. Without a single agreed location, partners had to special-case each endpoint ( purchase_details.new_balance , send_details.new_balance , transfer_details.new_balance , etc.). One missed branch = a stranded wallet showing a stale number. The canonical location eliminates that class of bug — same field name, same place, every endpoint. Where to read it Endpoint Side affected new_balance reflects /api/currency-purchases/purchase-currency Player credit Player's balance after the purchase credit /api/item-purchases/purchase-item Player debit Player's balance after the item debit /api/transfers/initiate-transfer Source player reservation Source's available_balance post-reservation /api/transfers/verify-sms no funds movement Source's available_balance (re-confirmation) /api/transfers/claim-transfer Target player credit Target's available_balance post-credit /api/currency-sends/initiate-send Sender reservation Sender's available_balance post-reservation /api/currency-sends/verify-sms no funds movement Sender's available_balance (re-confirmation) /api/currency-sends/claim-currency Receiver credit Receiver's available_balance post-credit Field shape Type Decimal-as-string. Always parse defensively: // JS / TS const newBalance = response.new_balance != null ? new Decimal(response.new_balance) : null; # Python from decimal import Decimal new_balance = ( Decimal(response["new_balance"]) if response.get("new_balance") is not None else None ) Units Game currency (the destination tenant's branded currency). The currency_name field in the same response tells you which one. Not USD. If you display in USD on your wallet UI, convert using the destination tenant's exchange rate. When new_balance is null Only one case: POST /api/currency-purchases/purchase-currency returning status: "requires_action" (3D Secure / SCA). The user must complete additional authentication; no credit has happened yet, so there's no new balance to report. The field is explicitly null (not missing) so your code can branch on status : if (response.status === 'success' && response.new_balance != null) { // safe to update wallet UI updateWalletBalance(new Decimal(response.new_balance)); } else if (response.status === 'requires_action') { // 3DS challenge — pass response.client_secret to your card processor's // SDK. INVO's auth challenge uses the automatic-confirmation flow, so // call the SDK's "confirm payment" variant (which confirms AND runs the // challenge), not a manual-confirm-only handler. await processor.confirmCardPayment(response.client_secret); } On every other success path (200/201 with status: "success" ), new_balance is non-null. The field is always present in success responses — never undefined. Belt-and-suspenders: trust GET /player-balances Recommended pattern Use the response's new_balance for fast wallet updates, but treat GET /api/player-balances/player/by-email/<email> as the source of truth. After any successful write, kick off a background read to reconfirm. Mid-deploy, network hiccup, or a stale write-response shape will never strand a user as long as you re-read. async function purchaseAndUpdate(usdAmount) { const response = await api.purchaseCurrency({ usd_amount: usdAmount }); if (response.status === 'success' && response.new_balance != null) { // fast path: optimistically update from write response setWalletBalance(new Decimal(response.new_balance)); } // belt: always reconcile against authoritative read endpoint const fresh = await api.getPlayerBalance({ player_email }); setWalletBalance(new Decimal(fresh.available_balance)); } Backwards-compatible aliases Partners that integrated before the canonical location was nailed down can still read from the legacy nested fields. Both are populated to the same value; new integrations should use the top-level field. Endpoint Legacy location /currency-purchases/purchase-currency purchase_details.new_balance /item-purchases/purchase-item balance_info.new_balance /transfers/claim-transfer transfer_details.new_balance /currency-sends/claim-currency send_details.new_balance

---

## Initiate Transfer

URL: https://docs.invo.network/docs/initiate-transfer
Endpoint: POST /api/transfers/initiate-transfer

Learn how to initiate cross-game transfers for players using Invo Network Transfer API.

Initiate Cross-Game Transfer Start a secure transfer of in-game currency to another game in your ecosystem. This endpoint handles validation, fee calculation, balance reservation, and SMS verification initiation for cross-game transfers. Transfer vs Currency Send Cross-Game Transfers are for moving currency from your game to another specific game where the same player will receive it. For player-to-player currency sends (including peer-to-peer within your game), use the /api/currency-sends/initiate-send endpoint instead. Key Difference: Transfers move currency between games for the same player account, while Currency Sends allow any player to send currency to any other player via phone number. POST /api/transfers/initiate-transfer Initiates a cross-game transfer with SMS verification Security Requirement This endpoint must only be called from your secure game server. Never call it directly from a game client. Authentication Required All requests must include your game's secret key in the request headers: X-Game-Secret-Key: your_game_secret_key_here Request Body Parameters Parameter Type Required Description client_request_id string Yes Unique ID for this transfer attempt (prevents duplicates) source_player_name string Yes Display name of the player initiating the transfer source_player_email string Yes Email address of the source player source_player_phone string Yes Phone number for SMS verification (format: +1234567890) target_player_email string Yes 🔒 SECURITY: Email address of intended recipient. Required as of 2026-05-07 so the phone-share approval gate can fire at initiate time, before any transaction is staged. If this email is new on the network and the supplied phone is already on file under a different email, the response is a 409 PHONE_SHARE_APPROVAL_REQUIRED with an SMS auto-sent to the existing phone owner. target_player_phone string Yes 🔒 SECURITY: Phone number of intended recipient. Claim code can ONLY be redeemed by this number (format: +1234567890) target_game_id integer Yes ID of the destination game (must be different from source game) amount string Yes Amount to transfer (as decimal string, e.g. "100.50") Implementation Examples Unity Unity C# Transfer Initiation // This function MUST be called on your secure server, NOT the client. public IEnumerator InitiateTransfer(string clientRequestId, string playerName, string playerEmail, string playerPhone, string targetPlayerEmail, string targetPlayerPhone, int targetGameId, string amount, Action<string> onSuccess, Action<string> onError) { string url = "https://invo.network/api/transfers/initiate-transfer"; var requestData = new { client_request_id = clientRequestId, source_player_name = playerName, source_player_email = playerEmail, source_player_phone = playerPhone, target_player_email = targetPlayerEmail, // REQUIRED 2026-05-07: gates phone-share check at initiate target_player_phone = targetPlayerPhone, // SECURITY: Claim code can only be used by this phone target_game_id = targetGameId, // Must be different from your game ID amount = amount }; string jsonBody = JsonUtility.ToJson(requestData); using (UnityWebRequest request = new UnityWebRequest(url, "POST")) { byte[] bodyRaw = System.Text.Encoding.UTF8.GetBytes(jsonBody); request.uploadHandler = new UploadHandlerRaw(bodyRaw); request.downloadHandler = new DownloadHandlerBuffer(); request.SetRequestHeader("X-Game-Secret-Key", "your_game_secret_key_here"); request.SetRequestHeader("Content-Type", "application/json"); yield return request.SendWebRequest(); if (request.result == UnityWebRequest.Result.Success) { onSuccess?.Invoke(request.downloadHandler.text); } else { onError?.Invoke(request.error + ": " + request.downloadHandler.text); } } } Unreal Unreal C++ Transfer Initiation // This function MUST be called on your secure server. void AYourGameMode::InitiateTransfer(const FString& ClientRequestId, const FString& PlayerName, const FString& PlayerEmail, const FString& PlayerPhone, const FString& TargetPlayerEmail, const FString& TargetPlayerPhone, int32 TargetGameId, const FString& Amount) { TSharedPtr<FJsonObject> RequestObj = MakeShareable(new FJsonObject); RequestObj->SetStringField("client_request_id", ClientRequestId); RequestObj->SetStringField("source_player_name", PlayerName); RequestObj->SetStringField("source_player_email", PlayerEmail); RequestObj->SetStringField("source_player_phone", PlayerPhone); RequestObj->SetStringField("target_player_email", TargetPlayerEmail); // REQUIRED 2026-05-07: gates phone-share check at initiate RequestObj->SetStringField("target_player_phone", TargetPlayerPhone); // SECURITY: Claim code can only be used by this phone RequestObj->SetNumberField("target_game_id", TargetGameId); RequestObj->SetStringField("amount", Amount); FString RequestBody; TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&RequestBody); FJsonSerializer::Serialize(RequestObj.ToSharedRef(), Writer); TSharedRef<IHttpRequest> Request = FHttpModule::Get().CreateRequest(); Request->SetURL("https://invo.network/api/transfers/initiate-transfer"); Request->SetVerb("POST"); Request->SetHeader("X-Game-Secret-Key", "your_game_secret_key_here"); Request->SetHeader("Content-Type", "application/json"); Request->SetContentAsString(RequestBody); Request->OnProcessRequestComplete().BindUObject(this, &AYourGameMode::OnTransferInitiated); Request->ProcessRequest(); } Godot Godot GDScript Transfer Initiation # This function MUST be called on your secure server. func initiate_transfer(client_request_id: String, player_name: String, player_email: String, player_phone: String, target_player_email: String, target_player_phone: String, target_game_id: int, amount: String): var url = "https://invo.network/api/transfers/initiate-transfer" var headers = [ "X-Game-Secret-Key: your_game_secret_key_here", "Content-Type: application/json" ] var body = { "client_request_id": client_request_id, "source_player_name": player_name, "source_player_email": player_email, "source_player_phone": player_phone, "target_player_email": target_player_email, # REQUIRED 2026-05-07: gates phone-share check at initiate "target_player_phone": target_player_phone, # SECURITY: Claim code can only be used by this phone "target_game_id": target_game_id, # Must be different from your game ID "amount": amount } http_request.request(url, headers, HTTPClient.METHOD_POST, JSON.stringify(body)) Request & Response Examples Example Request POST /api/transfers/initiate-transfer Content-Type: application/json X-Game-Secret-Key: your_game_secret_key_here { "client_request_id": "transfer_12345_20240624", "source_player_name": "PlayerOne", "source_player_email": "player@example.com", "source_player_phone": "+1234567890", "target_player_email": "recipient@example.com", "target_player_phone": "+0987654321", "target_game_id": 987654321098, "amount": "500.00" } // Note: target_game_id must be different from your game ID // Note: target_player_email is REQUIRED as of 2026-05-07 — required so the // phone-share approval gate can fire at initiate time, before any // transaction is staged. See PHONE_SHARE_APPROVAL_REQUIRED docs. Watch for HTTP 202 — guardian approval pending If the initiating account is flagged as a minor on Invo, this endpoint returns 202 Accepted instead of 201, with a guardian_approval block. The transaction is held until the guardian replies YES or NO via SMS within 15 minutes. This is the standard integration pattern going forward — handle it defensively on every initiate call ; you can't detect minor status from the partner side. Full contract: Guardian Approval . Success Response (201 Created) { "status": "success", "message": "Transfer initiated. Please verify with the SMS PIN sent to your phone.", "transaction_id": "txn_abc123def456", "order_id": "TFRO_1719235200_A1B2C3D4", "new_balance": "1500.00", "currency_name": "Gold", "verification_method": "sms", "verification_expires_at": "2026-01-01T12:10:00Z", "transfer_details": { "source_game": "Adventure Quest", "target_game": "Space Warriors", "target_game_id": "987654321098", "currency": "Gold", "currency_id": 1, "amount_initiated": "500.00", "fees_preview": { "total_fee": "50.00", "source_game_fee": "17.50", "target_game_fee": "17.50", "invo_fee": "15.00", "net_amount": "450.00", "source_rate_pct": "3.500", "target_rate_pct": "3.500" }, "transfer_policy": { "source_universal_transfers": "yes", "policy_applied": "universal", "target_in_linked_list": null } }, "verification_required": { "phone_number_masked": "******7890", "pin_expires_in_minutes": 10 } } Top-level new_balance is the canonical post-write balance (the source player's available balance after the transfer amount is reserved) — display this value rather than recomputing. currency_name names the source currency, and fees_preview also returns the per-side rate keys source_rate_pct and target_rate_pct . Branch on verification_method verification_method is 'in_app' | 'sms' . It is 'sms' for every game today, and whenever the proactive SMS PIN was sent. It is 'in_app' only when in-app verification is enabled for your game and the sender is enrolled — in that case the proactive SMS PIN is suppressed. When the value is 'in_app' , show the in-app approval panel and call POST /api/sdk/transfers/ {id} /approve instead of the SMS-code entry screen. When it is 'sms' , show the SMS PIN screen as usual. verification_expires_at is the ISO timestamp marking the end of the verification window. Pending Guardian Approval (202 Accepted) { "status": "pending_guardian_approval", "message": "Transfer initiated. SMS PIN sent to your phone, but verification is held until the guardian on file approves via SMS.", "transaction_id": "txn_abc123def456", "order_id": "TFRO_1719235200_A1B2C3D4", "guardian_approval": { "approval_id": "1f2a8c0d-...", "state": "pending", "expires_at": "2026-05-04T22:15:00+00:00", "poll_endpoint": "/api/transactions/txn_abc123def456/approval-status" }, "transfer_details": { /* same as 201 success */ }, "verification_required": { /* same as 201 success */ } } Show a "waiting for parent approval" UI and poll poll_endpoint every 5–10s. See Guardian Approval for the full state machine. Error Response - Phone-Share Approval Required (409 Conflict) { "status": "error", "error_code": "PHONE_SHARE_APPROVAL_REQUIRED", "message": "This phone number is already linked to another Invo account. The existing phone owner must approve via SMS before this email can also use this phone.", "phone": "+15551234567", "requesting_email": "bob@example.com", "existing_account_hints": ["al***@example.com"], "next_endpoint": "/api/wallet/phone-share/initiate", "approval_id": "1f2a8c0d-...", "expires_at": "2026-05-04T22:25:00+00:00", "code_sent": true, "already_approved": false } Fires when the supplied phone is already on file with a different email and no approval is recorded. Same contract for game-developer SDK integrations and platform-tier partners. The OTP SMS is auto-sent — Invo texts the code to the existing phone owner before returning the 409. Streamlined recovery: have the owner read the SMS, then call POST /api/wallet/phone-share/approve with the approval_id from the body and the 6-digit OTP, then retry the original call. Only call /phone-share/initiate manually if code_sent: false (Twilio outage fallback). Match on error_code , not message text . Initiate-time gate (since 2026-05-07): the gate now fires at /initiate-transfer as well as /claim-transfer . Previously the conflict was only detected at claim time, after the sender had reserved funds and received an SMS-PIN. Now the 409 fires at initiate, before any Transaction , TransferPin , or OrderBook row is created. Net effect: zero side effects until the existing phone owner has approved. If already_approved: true : auto-retry the original action immediately, do not show the OTP entry UI. The flag means a concurrent approval landed between gate-check and response — the pair is approved on the backend; the gate fired in a brief race window. The retry will succeed. One retry, no loops. Anti-abuse fields (optional, present only when triggered): cooldown_seconds appears when a fresh OTP for the same (phone, email) was minted less than 30s ago — no new SMS is sent , the previous code on the user's phone is still valid, and the included approval_id is the same row. Show the OTP entry panel as normal; do not show "code not sent" copy and do not auto-call /phone-share/initiate until the cooldown elapses. rate_limited: true + retry_after_seconds appear when this phone has hit the platform-wide 40-OTP-per-hour cap — no SMS sent, no approval_id returned, surface "please wait before requesting another code." Three valid response paths the existing phone owner can choose between: Approve via UI: type the 6-digit code into your UI → call POST /api/wallet/phone-share/approve with { approval_id, otp } . Approve via SMS reply: text the code (or YES <code> ) back from their phone. Invo's inbound webhook stamps the approval server-side. Reject (new, 2026-05-14): either call POST /api/wallet/phone-share/reject with { approval_id, otp } from your UI, OR reply NO (or NO <code> ) by SMS from the phone on file. Rejected rows are terminal — the requesting email must re-trigger a fresh request to retry. A subsequent /phone-share/initiate for the same pair creates a new approval row. If a user takes either SMS path, your client gets no direct callback — poll GET /api/wallet/phone-share/status?phone=...&email=... every 3–5s while your panel is open. Auto-retry the original action when approved: true ; surface a clear rejection message and offer a "try again" affordance if the user reports a NO reply (the status endpoint returns approved: false for both pending and rejected states — distinguishable only by the existence of a newer pending row after a fresh initiate). Error Response - Self Transfer (400 Bad Request) { "status": "error", "message": "Self-transfers are not allowed." } Error Response - Policy Violation (403 Forbidden) { "status": "error", "message": "Transfer not allowed: Target game 'Space Warriors' (ID: 987654321098) is not in the linked games list for source game 'Adventure Quest'. Linked games: [123456789012, 456789012345]", "error_code": "TRANSFER_POLICY_VIOLATION" } Error Response - Steam Value Not Transferable (409 Conflict) { "status": "error", "error_code": "STEAM_VALUE_NON_TRANSFERABLE", "message": "Currency purchased through Steam can only be used within Steam titles and can't be transferred here.", "transferable_max": "150.00", "steam_origin_amount": "350.00" } Fires when the player tries to move more than their non-Steam-origin balance to a non-Steam destination. Currency a player buys through Steam stays within Steam-distributed titles. transferable_max is how much they can still send to this destination (their non-Steam portion); steam_origin_amount is the Steam-purchased portion that is locked to Steam titles. Offer to retry at or below transferable_max . Match on error_code , not message text. These two Steam-containment errors only appear when a Steam-distributed title is on one side of the move — a per-title setting configured by the platform. Most integrations never see them. Error Response - Non-Steam Value Into Steam Title (409 Conflict) { "status": "error", "error_code": "NON_STEAM_VALUE_INTO_STEAM_BLOCKED", "message": "This title only accepts currency from other Steam titles." } Fires when transferring from a non-Steam game into a Steam-distributed title — non-Steam currency can't enter Steam titles. Match on error_code , not message text. Error Response - Rate Limited (429 Too Many Requests) { "error": "velocity_limit_exceeded", "message": "Hourly transfer limit of 10 transfers exceeded. Please try again later." } What Happens After Initiation SMS PIN Sent The player receives an SMS with a 6-digit verification PIN at the provided phone number. The message format is: "Your Invo transfer from Adventure Quest to Space Warriors verification code is 123456. Valid for 10 minutes. Our employees will never ask you for this code." Funds Reserved The transfer amount is immediately reserved from the player's available balance. This ensures the funds are secured for the transfer but not yet deducted. If the transfer fails or expires, the reserved amount is automatically returned to their available balance. Next Steps The player has 10 minutes to verify the SMS PIN using the /verify-sms endpoint. After verification, a claim code will be generated and sent to the player, which can then be used in the target game. Validation Rules & Restrictions Phone Number Format • Must start with country code (e.g., +1 for US) • Must be 10-15 digits total after country code • Only digits allowed after the + symbol • Examples: +1234567890, +441234567890 Transfer Amount Limits • Must be greater than currency minimum (usually 0.01) • Must not exceed currency maximum (if set by game) • Must not exceed player's available balance • Daily transfer limit: configurable per-game daily limit (default 1,000,000 currency units, adjustable by the platform) • Hourly transfer limit: 10 transfers per player Game Status Requirements • Source Game: Must be in 'live' status (not 'testing') • Target Game: Must be in 'live' status (not 'testing') • Self-Transfers: Not allowed (use currency sends instead) • Cross-Game: Requires both games to be live and policy-compliant Transfer Policy Requirements • Universal Transfers (universal_transfers: "yes"): Can transfer to any live game • Linked Transfers (universal_transfers: "no"): Can only transfer to games in linked_game_ids • Source game must have allows_outgoing_transfers enabled • Target game must have allows_incoming_transfers enabled • Target game must be found in ecosystem Duplicate Prevention • client_request_id must be unique per game • Rapid identical transfers (same amount/target) are blocked • Rate limiting prevents spam attempts • Velocity limits prevent excessive transfer activity Implementation Best Practices User Experience • Use the /available-destinations endpoint to get valid target games • Validate phone number format before submitting • Show transfer fee preview before confirmation • Display clear error messages for validation failures • Provide phone number formatting hints (+1234567890) • Show target game name clearly in transfer UI • Explain the difference between transfers and currency sends Error Handling • Parse API error responses for user-friendly messages • Handle rate limiting with appropriate retry delays • Implement exponential backoff for server errors • Log all transfer attempts for debugging • Provide fallback options when services are unavailable • Handle policy violations gracefully with clear explanations Security • Always call from secure server, never from game client • Validate all input data before API submission • Use unique client_request_id for each transfer • Implement proper timeout handling • Never expose game secret keys in client code • Validate target_game_id against allowed destinations Transfer Flow • Save transaction_id for subsequent verification calls • Display SMS PIN entry UI immediately after success • Show countdown timer for PIN expiration (10 minutes) • Provide option to cancel transfer before verification • Update player balance display to show reserved amount • Inform player that claim code will be generated after verification Integration Checklist Before Going Live Game secret key securely stored and never exposed to clients Transfer API endpoints called only from secure server Available destinations endpoint integrated for target game selection Phone number validation implemented on client side Error handling covers all documented HTTP status codes Rate limiting handled gracefully with user feedback Transfer fees clearly displayed to users SMS PIN verification flow implemented Claim code sharing mechanism implemented Balance updates reflected correctly in UI Testing completed with both successful and failed scenarios Self-transfer prevention implemented (redirect to currency sends)

---

## Verify Transfer

URL: https://docs.invo.network/docs/verify-transfer
Endpoint: POST /api/transfers/verify-sms

Verify cross-game transfers using SMS PIN verification for secure player transactions.

Verify SMS PIN Verify the SMS PIN to authorize a transfer. This endpoint validates the PIN sent to the player's phone and, upon success, generates a claim code that can be shared with the intended recipient. POST /api/transfers/verify-sms Verifies the SMS PIN and authorizes the transfer Authentication Required Must include the same game secret key used to initiate the transfer: X-Game-Secret-Key: your_game_secret_key_here Request Body Parameters Parameter Type Required Description transaction_id string Yes Transaction ID returned from initiate-transfer sms_pin string Yes 6-digit PIN received via SMS SMS PIN Requirements PIN Format • 6-digit numeric code • Case-sensitive (numbers only) • Unique per transfer attempt • One-time use only Time Limits • PIN expires in 10 minutes • Maximum 3 verification attempts • Failed attempts count toward rate limits • Expired PINs cannot be reused Implementation Examples Unity Unity C# SMS Verification // This function MUST be called on your secure server, NOT the client. public IEnumerator VerifySMSPin(string transactionId, string smsPin, Action<string> onSuccess, Action<string> onError) { string url = "https://invo.network/api/transfers/verify-sms"; var requestData = new { transaction_id = transactionId, sms_pin = smsPin }; string jsonBody = JsonUtility.ToJson(requestData); using (UnityWebRequest request = new UnityWebRequest(url, "POST")) { byte[] bodyRaw = System.Text.Encoding.UTF8.GetBytes(jsonBody); request.uploadHandler = new UploadHandlerRaw(bodyRaw); request.downloadHandler = new DownloadHandlerBuffer(); request.SetRequestHeader("X-Game-Secret-Key", "your_game_secret_key_here"); request.SetRequestHeader("Content-Type", "application/json"); yield return request.SendWebRequest(); if (request.result == UnityWebRequest.Result.Success) { onSuccess?.Invoke(request.downloadHandler.text); } else { onError?.Invoke(request.error + ": " + request.downloadHandler.text); } } } Unreal Unreal C++ SMS Verification // This function MUST be called on your secure server. void AYourGameMode::VerifySMSPin(const FString& TransactionId, const FString& SMSPin) { TSharedPtr<FJsonObject> RequestObj = MakeShareable(new FJsonObject); RequestObj->SetStringField("transaction_id", TransactionId); RequestObj->SetStringField("sms_pin", SMSPin); FString RequestBody; TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&RequestBody); FJsonSerializer::Serialize(RequestObj.ToSharedRef(), Writer); TSharedRef<IHttpRequest> Request = FHttpModule::Get().CreateRequest(); Request->SetURL("https://invo.network/api/transfers/verify-sms"); Request->SetVerb("POST"); Request->SetHeader("X-Game-Secret-Key", "your_game_secret_key_here"); Request->SetHeader("Content-Type", "application/json"); Request->SetContentAsString(RequestBody); Request->OnProcessRequestComplete().BindUObject(this, &AYourGameMode::OnSMSVerified); Request->ProcessRequest(); } Godot Godot GDScript SMS Verification # This function MUST be called on your secure server. func verify_sms_pin(transaction_id: String, sms_pin: String): var url = "https://invo.network/api/transfers/verify-sms" var headers = [ "X-Game-Secret-Key: your_game_secret_key_here", "Content-Type: application/json" ] var body = { "transaction_id": transaction_id, "sms_pin": sms_pin } http_request.request(url, headers, HTTPClient.METHOD_POST, JSON.stringify(body)) Request & Response Examples Example Request POST /api/transfers/verify-sms Content-Type: application/json X-Game-Secret-Key: your_game_secret_key_here { "transaction_id": "txn_abc123def456", "sms_pin": "123456" } Guardian-approval-aware responses If the original transaction was initiated by a minor account, this endpoint may return: 202 GUARDIAN_APPROVAL_PENDING — guardian hasn't replied yet. The same call succeeds normally once approval lands; just keep polling. 410 GUARDIAN_APPROVAL_REJECTED or GUARDIAN_APPROVAL_EXPIRED — terminal. Show a clear message; user must re-initiate. Full state machine: Guardian Approval . Success Response (200 OK) { "status": "success", "message": "SMS verification successful. Transfer is now pending claim by receiver.", "transaction_id": "txn_abc123def456", "new_balance": "750.00", "claim_code": "KJMRS-47281", "claim_instructions": { "message": "Provide this claim code to the intended receiver.", "target_game_id": "42", "target_game_name": "Space Warriors", "claim_code_expires_at": "2024-06-25T14:30:00Z" }, "transfer_summary": { "amount_initiated": "500.00", "net_amount_for_claim": "450.00", "fees_deducted": "50.00", "source_player_current_available_balance": "750.00" }, "order_id": "TFRO_1719235200_A1B2C3D4" } Error Response - Invalid PIN (400 Bad Request) { "status": "error", "message": "Invalid SMS PIN.", "attempts_remaining": 2 } Error Response - Expired PIN (400 Bad Request) { "status": "error", "message": "SMS PIN is not valid: PIN expired." } Error Response - Rate Limited (429 Too Many Requests) { "error": "sms_verification_blocked", "message": "Too many SMS verification attempts. Please try again in 10 minutes.", "retry_after": 600 } Resend Verification PIN POST /api/transfers/resend-pin Re-sends the same still-valid PIN if the first SMS didn't arrive If the player never received the first SMS, you can re-queue the same verification PIN for delivery. This does not generate a new PIN — the original code and its expiry are unchanged. Once the PIN has expired, re-initiate the transfer instead. Authentication Required Uses the same game secret key as initiate and verify: X-Game-Secret-Key: your_game_secret_key_here Request Body Parameters Parameter Type Required Description transaction_id string Yes Transaction ID returned from initiate-transfer. No sms_pin is sent — the original PIN is re-used. Example Request POST /api/transfers/resend-pin Content-Type: application/json X-Game-Secret-Key: your_game_secret_key_here { "transaction_id": "txn_abc123def456" } Response Codes Status Body Meaning 200 { "status": "resent" } The same PIN was re-queued for delivery. 429 { "error": "resend_cooldown", "retry_after": <seconds> } Requested too soon. Wait retry_after seconds before retrying (cooldown is 30s). 400 { "error": "pin_expired", "message": "Start a new transfer." } The PIN has already expired. No new PIN is minted — re-initiate the transfer instead. 400 Wrong state / missing field Transaction is not pending verification, or transaction_id is missing. 404 Not found Transaction not found, or it belongs to another game. 401 Unauthorized Bad or missing X-Game-Secret-Key . 503 { "error": "resend_unavailable" } Resend may be unavailable in some environments (e.g. sandbox today). Fall back to re-initiating the transfer. Recommended integrator flow PIN not received and not yet expired → call resend-pin (respect the 30s cooldown / retry_after ). On pin_expired or resend_unavailable (503) → re-initiate the transfer. Rate Limiting • 10 resends per hour per transaction • 60 resends per hour per source IP • Separate from the verify-sms rate limits • 30-second cooldown between consecutive resends What Happens After Successful Verification Claim Code Generated A unique claim code is generated and included in the response. This code is also sent via SMS to the sender for easy sharing. "Your Invo transfer to Space Warriors claim code is KJMRS-47281. Valid for 24 hours. Our employees will never ask you for this code." Transfer Status Updated The transfer status changes from "pending_pin_verification" to "pending_claim". The funds remain reserved in the sender's account until the transfer is either claimed or expires. 24-Hour Claim Window The recipient has 24 hours to claim the transfer using the claim code. If not claimed within this time, the transfer expires and the net amount (minus fees) is automatically returned to the sender's balance. Security Features PIN Protection • Hashed storage - PINs never stored in plain text • Limited attempts - Maximum 3 verification tries • Time-based expiry - 10 minute validity window • One-time use - PIN becomes invalid after successful verification Rate Limiting • 40 verification attempts per hour per player • 20 attempts per minute per transaction • 200 attempts per hour per IP address • Failed attempts trigger progressive blocking Fraud Detection • SMS verification spam detection • Invalid PIN attempt tracking • IP-based suspicious activity monitoring • Automatic blocking for repeated failures Transaction Integrity • Funds remain reserved during verification • Automatic cleanup of expired transactions • Comprehensive audit trail • Circuit breaker for service protection Common Error Scenarios HTTP 400 - Bad Request • Invalid SMS PIN: PIN doesn't match or has wrong format • PIN expired: More than 10 minutes have passed since initiation • Max attempts reached: 3 incorrect PIN attempts used up • Missing parameters: transaction_id or sms_pin not provided • Wrong transfer state: Transfer not in pending_pin_verification status HTTP 404 - Not Found • Transaction not found: Invalid transaction_id or wrong game • Unauthorized access: Game secret key doesn't match transfer source HTTP 429 - Too Many Requests • SMS verification spam: Too many verification attempts from player • Transaction rate limit: Too many attempts for specific transaction • IP rate limit: Too many requests from the same network • Invalid PIN blocking: Player blocked due to repeated invalid PINs HTTP 500 - Server Error • Database connectivity: Temporary database issues • SMS service error: Unable to send claim code SMS • Circuit breaker open: Service temporarily unavailable Implementation Best Practices User Experience • Display remaining attempts when PIN verification fails • Show countdown timer for PIN expiration • Provide clear error messages for different failure scenarios • If the PIN didn't arrive but hasn't expired, use resend-pin to re-send the same code; only re-initiate the transfer once the PIN has expired Error Handling • Parse error responses to show appropriate user messages • Handle rate limiting with retry logic and user feedback • Implement exponential backoff for server errors • Log all API responses for debugging and monitoring Security • Never log or store SMS PINs in your application • Validate PIN format on client side before sending • Clear PIN input fields after submission • Use HTTPS for all API communications Claim Code Sharing • Display claim code prominently after successful verification • Provide easy copy-to-clipboard functionality • Show target game name and expiration time clearly • Consider QR code generation for mobile sharing

---

## Claim Transfer

URL: https://docs.invo.network/docs/claim-transfer
Endpoint: POST /api/transfers/claim-transfer

Complete cross-game transfers by claiming transferred value in the destination game.

Claim Cross-Game Transfer Complete a cross-game transfer by claiming the funds with a claim code. This endpoint validates the claim code, creates or updates the recipient player, and credits the transferred currency to their balance. First — discover what's waiting To find which transfers are pending for a player (without already knowing the transaction id or claim code), call GET /api/transfers/inbound-pending?player_email=… (target game's secret key). It returns the live unclaimed transfers/sends addressed to that player at your game — each with to_phone , amount , source_game , and claim_code_expires_at — so you can badge "you have X to collect." See Webhooks & receiving money for the full shape and the webhook wake-up pattern. POST /api/transfers/claim-transfer Claims a transfer using the provided claim code Authentication Required Must include the target game's secret key (where the funds will be received): X-Game-Secret-Key: target_game_secret_key_here Request Body Parameters Parameter Type Required Description claim_code string Yes Claim code received from SMS or transfer initiator. Format is ABCDE-12345 — 5 uppercase letters (excluding O ) + hyphen + 5 digits (excluding 0 ). Total 11 characters. Case-sensitive. target_player_name string Yes Display name of the player claiming the transfer target_player_email string Yes Email address of the recipient player target_player_phone string (E.164) Yes 🔒 SECURITY: Phone of the claiming player. MUST match the target_player_phone sent at initiation. Strict E.164 — leading + is required (e.g., +15551234567 ). Without the + the request returns 400 "Phone number must start with country code." See callout below. target_currency_id integer Yes Currency ID in the target game where funds will be credited Phone format — strict E.164 target_player_phone is validated as strict E.164: a leading + followed by 10–15 digits. Common formatting ( (555) 123-4567 , spaces, dashes) is stripped server-side, but the + itself is required . Without it the backend returns: {"status": "error", "message": "Phone number must start with country code (e.g., +1234567890)"} The backend will not auto-prepend a default country code (e.g., assuming 5551234567 means +1 ) because the universal player identity hash and cross-tenant phone-binding security check require phones to canonicalize identically across tenants — guessing would silently misalign US and Canadian numbers with the same trailing digits. Your UI should canonicalize before submit. Either use a phone-input component that always emits E.164 ( react-phone-number-input , libphonenumber-js ), or normalize manually: function toE164(input, defaultCountry = 'US') { if (!input) return null; if (input.startsWith('+')) return input.replace(/[^\d+]/g, ''); const digits = input.replace(/\D/g, ''); if (defaultCountry === 'US' && digits.length === 10) return `+1${digits}`; if (defaultCountry === 'US' && digits.length === 11 && digits[0] === '1') return `+${digits}`; return null; // ambiguous — surface a 'include country code' hint } The same rule applies to every phone field on every transfer/send endpoint ( source_player_phone , target_player_phone , receiver_player_phone ) — fix it once at your input layer. Claim Code Requirements Code Format • Format: ABCDE-12345 (5 letters · hyphen · 5 digits, 11 chars total) • Uppercase letters only, excluding O (to avoid 0/O confusion) • Digits 1–9 only, excluding 0 (same reason) • Case-sensitive, unique per transfer, one-time use • Example: KJMRS-47281 Time Limits • Code expires in 24 hours • Maximum 5 claim attempts • Failed attempts count toward rate limits • Expired codes cannot be reused Implementation Examples Unity Unity C# Transfer Claim // This function MUST be called on your secure server, NOT the client. public IEnumerator ClaimTransfer(string claimCode, string playerName, string playerEmail, string playerPhone, int targetCurrencyId, Action<string> onSuccess, Action<string> onError) { string url = "https://invo.network/api/transfers/claim-transfer"; var requestData = new { claim_code = claimCode, target_player_name = playerName, target_player_email = playerEmail, target_player_phone = playerPhone, target_currency_id = targetCurrencyId }; string jsonBody = JsonUtility.ToJson(requestData); using (UnityWebRequest request = new UnityWebRequest(url, "POST")) { byte[] bodyRaw = System.Text.Encoding.UTF8.GetBytes(jsonBody); request.uploadHandler = new UploadHandlerRaw(bodyRaw); request.downloadHandler = new DownloadHandlerBuffer(); request.SetRequestHeader("X-Game-Secret-Key", "target_game_secret_key_here"); request.SetRequestHeader("Content-Type", "application/json"); yield return request.SendWebRequest(); if (request.result == UnityWebRequest.Result.Success) { onSuccess?.Invoke(request.downloadHandler.text); } else { onError?.Invoke(request.error + ": " + request.downloadHandler.text); } } } Unreal Unreal C++ Transfer Claim // This function MUST be called on your secure server. void AYourGameMode::ClaimTransfer(const FString& ClaimCode, const FString& PlayerName, const FString& PlayerEmail, const FString& PlayerPhone, int32 TargetCurrencyId) { TSharedPtr<FJsonObject> RequestObj = MakeShareable(new FJsonObject); RequestObj->SetStringField("claim_code", ClaimCode); RequestObj->SetStringField("target_player_name", PlayerName); RequestObj->SetStringField("target_player_email", PlayerEmail); RequestObj->SetStringField("target_player_phone", PlayerPhone); RequestObj->SetNumberField("target_currency_id", TargetCurrencyId); FString RequestBody; TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&RequestBody); FJsonSerializer::Serialize(RequestObj.ToSharedRef(), Writer); TSharedRef<IHttpRequest> Request = FHttpModule::Get().CreateRequest(); Request->SetURL("https://invo.network/api/transfers/claim-transfer"); Request->SetVerb("POST"); Request->SetHeader("X-Game-Secret-Key", "target_game_secret_key_here"); Request->SetHeader("Content-Type", "application/json"); Request->SetContentAsString(RequestBody); Request->OnProcessRequestComplete().BindUObject(this, &AYourGameMode::OnTransferClaimed); Request->ProcessRequest(); } Godot Godot GDScript Transfer Claim # This function MUST be called on your secure server. func claim_transfer(claim_code: String, player_name: String, player_email: String, player_phone: String, target_currency_id: int): var url = "https://invo.network/api/transfers/claim-transfer" var headers = [ "X-Game-Secret-Key: target_game_secret_key_here", "Content-Type: application/json" ] var body = { "claim_code": claim_code, "target_player_name": player_name, "target_player_email": player_email, "target_player_phone": player_phone, "target_currency_id": target_currency_id } http_request.request(url, headers, HTTPClient.METHOD_POST, JSON.stringify(body)) Request & Response Examples Example Request POST /api/transfers/claim-transfer Content-Type: application/json X-Game-Secret-Key: target_game_secret_key_here { "claim_code": "KJMRS-47281", "target_player_name": "PlayerTwo", "target_player_email": "player2@example.com", "target_player_phone": "+1987654321", "target_currency_id": 1 } Success Response (200 OK) { "status": "success", "message": "Transfer claimed successfully.", "transaction_id": "txn_abc123def456", "new_balance": "1450.00", "currency_name": "Gold", "transfer_details": { "amount_received": "450.00", "source_game": "Adventure Quest", "target_currency": "Gold", "target_player": "PlayerTwo", "new_balance": "1450.00" }, "completion_time": "2024-06-24T15:30:00Z", "order_id": "TFRO_1719235200_A1B2C3D4" } Top-level new_balance is the canonical post-write balance — the target player's available balance after the credit. The same value is mirrored in transfer_details.new_balance for legacy callers; prefer the top-level field. currency_name names the target currency credited. Error Response - Phone-Share Approval Required (409 Conflict) { "status": "error", "error_code": "PHONE_SHARE_APPROVAL_REQUIRED", "message": "This phone number is already linked to another Invo account. The existing phone owner must approve via SMS before this email can also use this phone.", "phone": "+15551234567", "requesting_email": "bob@example.com", "existing_account_hints": ["al***@example.com"], "next_endpoint": "/api/wallet/phone-share/initiate", "approval_id": "1f2a8c0d-...", "expires_at": "2026-05-04T22:25:00+00:00", "code_sent": true, "already_approved": false } Fires when the claiming player's email is new on a phone that's already on file with a different email. Same contract for game-developer SDK integrations and platform-tier partners. The OTP SMS is auto-sent — have the existing phone owner read the SMS, then call POST /api/wallet/phone-share/approve with the approval_id from the body and the 6-digit OTP, then retry the claim with the same claim code. Only call /phone-share/initiate manually if code_sent: false . Match on error_code , not message text . If already_approved: true : auto-retry the claim immediately, do not show the OTP entry UI. The flag means a concurrent approval landed between gate-check and response — the pair is approved on the backend; the gate fired in a brief race window. The retry will succeed. One retry, no loops. Anti-abuse fields (optional, present only when triggered): cooldown_seconds appears when a fresh OTP for the same (phone, email) was minted less than 30s ago — no new SMS is sent , the previous code on the user's phone is still valid, and the included approval_id is the same row. Show the OTP entry panel as normal; do not show "code not sent" copy and do not auto-call /phone-share/initiate until the cooldown elapses. rate_limited: true + retry_after_seconds appear when this phone has hit the platform-wide 40-OTP-per-hour cap — no SMS sent, no approval_id returned, surface "please wait before requesting another code." Two equally valid approval paths the user can choose between: (1) type the 6-digit code into your UI → call POST /api/wallet/phone-share/approve , or (2) text the code back from their phone (Invo's inbound webhook approves server-side). If a user takes path 2, your client gets no direct callback — poll GET /api/wallet/phone-share/status?phone=...&email=... every 3–5s while your panel is open and auto-retry the claim when approved: true . Account Selection — Multi-Email-on-Phone (200 OK with picker shape) { "status": "needs_account_selection", "claim_code": "ABCDE-12345", "message": "Multiple accounts share this phone number on the destination game and the supplied email did not match any of them. Re-submit with target_player_id set to the chosen account, or fix the target_player_email.", "candidates": [ { "player_id": 12345, "email_hint": "al***@example.com" }, { "player_id": 67890, "email_hint": "bo***@example.com" } ] } Why this fires: Invo's wallet model supports multiple emails on one verified phone (parent + child, two-account gamers, family-shared device). When the destination game has 2+ Player rows on the same phone, the claim endpoint resolves which one to credit using this priority order: target_player_id in the request body (must match a candidate) — your client's explicit picker selection. target_player_email matches exactly one candidate's email — the common case. The user already typed their email into your claim form, so we don't prompt twice. No picker fires. Picker response (the 200 above) — only when steps 1 and 2 both fail. Recovery: render a picker from candidates showing each email_hint , let the user tap one, then re-submit /claim-transfer with the same body PLUS target_player_id set to the chosen player_id . Status code is 200 not an error — the call hasn't failed, it just needs disambiguation. Most claims never see this response. It surfaces only in genuinely ambiguous cases (e.g., the user typo'd their email). Implementing the picker UI is a low-effort defensive measure — same shape applies to /claim-currency . Error Response - Invalid Claim Code (400 Bad Request) { "status": "error", "message": "Invalid claim code.", "attempts_remaining": 4 } Error Response - Wrong Claim Endpoint (400 Bad Request) Returned when a claim code exists for this game but was minted by the player-to-player send flow rather than the self-transfer flow. Switch your call to /api/currency-sends/claim-currency with receiver_* field names. { "status": "error", "error_code": "WRONG_CLAIM_ENDPOINT", "message": "This claim code is for a player-to-player currency send. Use POST /api/currency-sends/claim-currency instead.", "expected_endpoint": "/api/currency-sends/claim-currency", "expected_body_fields": [ "claim_code", "receiver_player_name", "receiver_player_email", "receiver_player_phone" ] } Switch on error_code === "WRONG_CLAIM_ENDPOINT" in your handler — the message text may evolve, but the code and expected_endpoint field are stable contract. Error Response - Expired Code (400 Bad Request) { "status": "error", "message": "Claim code is not valid: Claim code expired." } Error Response - Transfer Not Found (404 Not Found) { "status": "error", "message": "Invalid claim code or transfer not intended for this game." } Error Response - Phone Number Mismatch (403 Forbidden) { "status": "error", "message": "This claim code can only be redeemed by the phone number it was sent to. Phone number mismatch." } What Happens During a Successful Claim Currency Credited The net transfer amount (original amount minus fees) is immediately credited to the recipient's balance in the target game. If the player doesn't exist in the target game, a new player account is automatically created. Transfer Completed The transfer status is updated to "completed" and the transaction is finalized. The sender's reserved funds are permanently deducted, and fee distributions are recorded for all participating games and the platform. SMS Confirmation A confirmation SMS is sent to the recipient's phone number confirming the successful claim: "Invo Transfer Claimed: You have successfully claimed 450.00 Gold from a transfer via Adventure Quest." Automatic Player Creation New Player Handling If the recipient email doesn't exist in the target game, the system automatically creates a new player account with the provided information: • Player Name: Set from target_player_name • Email: Normalized and set from target_player_email • Phone: Set from target_player_phone • Balance: New currency balance created with claimed amount • Join Date: Set to current timestamp Note: If the player already exists, their name and phone number are updated with the new information if different. Security & Validation 🔒 BREAKING CHANGE: Phone-Based Security As of the latest update, claim codes can ONLY be redeemed by the exact phone number specified during transfer initiation via target_player_phone . • The target_player_phone provided during claim MUST exactly match the target_player_phone from initiation • Phone mismatch results in 403 Forbidden error • This prevents unauthorized claim code sharing and redemption • Enhances security for cross-game transfers Claim Code Validation • Hashed storage - codes never stored in plain text • Case-sensitive matching • Maximum 5 claim attempts per code • 24-hour expiration window • One-time use enforcement • Phone number verification required Rate Limiting • 30 claim attempts per hour per player • 15 attempts per minute per claim code • 150 attempts per hour per IP address • Progressive blocking for repeated failures Input Validation • Phone number format validation (+country code) • Email format validation • Currency ID must belong to target game • Player name length and character validation Fraud Prevention • Failed claim attempt tracking • IP-based suspicious activity monitoring • Game authorization validation • Circuit breaker for service protection Fee Distribution on Claim When a transfer is successfully claimed, the fee distribution is automatically processed: Source Game (3.5%) The game that sent the currency receives 3.5% of the original transfer amount as compensation for losing a player's funds. Target Game (3.5%) The game that receives the currency gets 3.5% of the original transfer amount as compensation for accepting new funds. Platform Fee (3.0%) Invo Network retains 3.0% of the original transfer amount for providing the secure transfer infrastructure. Common Error Scenarios HTTP 400 - Bad Request • Invalid claim code: Code doesn't match or has wrong format • Code expired: More than 24 hours have passed since generation • Max attempts reached: 5 incorrect claim attempts used up • Missing parameters: Required fields not provided • Wrong transfer state: Transfer not in pending_claim status • Invalid phone format: Phone number doesn't meet format requirements • Currency mismatch: target_currency_id doesn't belong to this game HTTP 403 - Forbidden • Phone number mismatch: target_player_phone doesn't match the phone from initiation • Unauthorized claim: Only the intended recipient can redeem this claim code HTTP 404 - Not Found • Transfer not found: Invalid claim code or transfer not intended for this game • Wrong target game: Transfer was meant for a different game • Currency not found: target_currency_id doesn't exist in this game HTTP 429 - Too Many Requests • Player rate limit: Too many claim attempts from this player • Claim code rate limit: Too many attempts for this specific claim code • IP rate limit: Too many requests from the same network • Invalid claim blocking: Player blocked due to repeated invalid claims • CLAIM_LOCKED (new, 2026-05-14): the DB-backed multi-dimensional lockout has tripped — see the dedicated error_code: CLAIM_LOCKED response below. HTTP 429 - CLAIM_LOCKED (multi-dimensional claim-attempt lockout) Shipped 2026-05-14. Replaces the old Redis-only claim_code_blocked counter (which failed open on Redis outage and could be evaded by rotating the submitted email). Every failed claim attempt — wrong code, wrong phone, wrong endpoint, wrong PIN — writes an audit row to claim_attempt_failures . ANY of three dimensions tripping locks the attempt out. HTTP/1.1 429 Too Many Requests Retry-After: 1800 { "status": "error", "error_code": "CLAIM_LOCKED", "error": "invalid_claim_code_blocked", "message": "Too many failed claim attempts for this phone number. Please wait 30 minutes before trying again.", "locked_dimension": "phone", "retry_after_seconds": 1800, "retry_after": 1800 } Two equivalent ways to match: new integrations should switch on error_code === "CLAIM_LOCKED" . Existing integrations whose security-block handler keys on the legacy field can switch on error === "invalid_claim_code_blocked" — both fields are present on every lockout response. Same goes for the duration field: retry_after_seconds (canonical) and retry_after (legacy alias) carry the same value. Dimension Threshold Window Lockout target_player_phone 5 failures trailing 30 min 30 min target_player_email 5 failures trailing 30 min 30 min ip_address 20 failures trailing 60 min 60 min Client behavior: match on error_code === "CLAIM_LOCKED" . Read retry_after_seconds (also exposed in the Retry-After header) to drive your back-off. The locked_dimension field is mainly informational — your UI should treat all three dimensions the same way (show the retry timer; don't leak which specific dimension tripped to the user, since that's enumeration-adjacent). locked_dimension: "db_unavailable" appears if Invo's audit DB is briefly unreachable (fail-CLOSED behavior); retry_after_seconds is 60s in that case — short retry, not a real lockout. HTTP 500 - Server Error • Database connectivity: Temporary database issues • SMS service error: Unable to send confirmation SMS • Circuit breaker open: Service temporarily unavailable • Fee distribution error: Error recording fee distributions (claim still succeeds) Important Implementation Notes Game Secret Key The X-Game-Secret-Key header must contain the secret key of the target game (where the funds will be received), not the source game. This ensures only authorized games can claim transfers intended for them. Atomic Operations The claim process is atomic - either the entire operation succeeds (currency credited, fees distributed, notifications sent) or it fails completely with no partial state changes. This ensures data consistency. Automatic Cleanup If claim codes expire (24 hours), the system automatically returns the net transfer amount to the sender's balance and marks the transfer as expired. No manual intervention is required. Implementation Best Practices User Experience • Provide clear claim code input validation • Display remaining attempts when claim fails • Show clear success messages with amount received • Update player balance immediately in UI after successful claim • Provide claim code format hints (e.g., "Enter code like: KJMRS-47281") Error Handling • Parse error responses to show user-friendly messages • Handle rate limiting gracefully with retry suggestions • Differentiate between expired codes and invalid codes • Log claim attempts for customer support purposes • Implement proper timeout handling for network requests Security • Never log or store claim codes in your application • Validate claim code format before API submission • Clear claim code input fields after processing • Use HTTPS for all API communications • Validate phone number format on client side Player Data • Pre-populate player fields if user is already logged in • Validate email format before submission • Ensure phone numbers include country codes • Show currency selection if multiple currencies available • Confirm player details before final claim submission

---

## Player-to-Player Sends

URL: https://docs.invo.network/docs/send-overview

Enable player-to-player currency sending and gifting functionality in your game.

Player-to-Player Currency Sends Overview Enable secure, verified currency sends directly between players, either within the same game or across different games. Our send system uses SMS verification and claim codes to ensure only authorized sends are completed. Steam-purchased currency stays within Steam titles Currency a player buys through Steam can move among Steam-distributed games but not to non-Steam games, and non-Steam currency can't move into Steam titles. This containment is configured per-title by the platform and does not affect games that aren't Steam-distributed. When it applies, non-Steam destinations are omitted from destination lists for Steam-purchased balances, and an over-limit or wrong-direction send is rejected with a STEAM_VALUE_NON_TRANSFERABLE or NON_STEAM_VALUE_INTO_STEAM_BLOCKED 409. Integration Flow for Game Developers Step 1: Get Available Destinations (Cache Daily) Before building your currency send UI, fetch the list of games your players can send currency to. This data should be cached locally and refreshed once per day. POST /api/currency-sends/available-destinations • Cache Duration: 24 hours (games don't change frequently) • Refresh Trigger: Daily app startup or manual refresh • Storage: Local file, localStorage, or in-memory cache • Performance: Prevents API calls every time player opens send UI 2 Build Currency Send UI Use the cached destination data to create your send interface. Show game names, icons, currency types, receiver phone input, and amount validation. UI Elements: Game selection dropdown, phone number input, currency display, amount input with min/max validation, fee preview. 3 Process Currency Send When player confirms send, call the initiate → verify → claim sequence using the currency send APIs. API Sequence: /initiate-send → /verify-sms → /claim-currency (receiver's game) Note: handle HTTP 202. If the sending account is flagged as a minor on Invo, /initiate-send returns 202 pending_guardian_approval with a polling endpoint. Adult accounts are unaffected. See Guardian Approval . Send Process 4 Steps Get Destinations → Initiate → Verify → Claim Security SMS + PIN Two-factor verification Send Fee 10% Platform + game fees Cache Duration 24 Hours Destinations API cache How Player-to-Player Currency Sends Work 0 Get Available Destinations (Daily) Before showing send options, your game calls the destinations API to get the current list of games players can send currency to. This data is cached locally for 24 hours for performance. What happens: API returns game list based on universal_transfers setting, data cached locally, send UI populated. 1 Initiate Currency Send Player selects destination game from cached list, enters receiver's phone number, amount, and confirms send. The system validates the send, calculates fees, and reserves the amount from their balance. 🔒 The claim code is locked to the receiver's phone. What happens: Amount is reserved, claim code locked to receiver phone, SMS PIN generated and sent to sender, send enters "pending verification" status. 2 SMS Verification Sender receives an SMS with a verification PIN (valid for 10 minutes). They enter this PIN in their game to confirm they authorized the send. This prevents unauthorized currency sends. What happens: PIN is verified, claim code is generated and sent to receiver via SMS, send enters "pending claim" status. 3 Claim Sent Currency Receiver uses the claim code in their game to receive the sent currency. 🔒 The claim code can ONLY be redeemed by the exact phone number specified during initiation. Valid for 24 hours, one-time use only. What happens: Phone number verified, currency credited to receiver's balance, send completed, confirmation SMS sent. Types of Currency Sends Same-Game Sends Send currency to another player within the same game. Perfect for peer-to-peer transactions, gifting, or marketplace purchases between players. • Instant delivery after verification • Same currency type maintained • Ideal for player-to-player trading • Community building features Cross-Game Sends Send currency to a player in a different game within your ecosystem. Enables value transfer across your entire game portfolio. • Cross-game value portability • Ecosystem connectivity • Player retention across games • Unified economy benefits Send Mode Logic Universal Sends When your game has universal_transfers = "yes" • Players can send to ALL live games • Includes same-game sends (peer-to-peer) • Maximum ecosystem connectivity • Excludes testing/inactive games Linked Sends When your game has universal_transfers = "no" • Players can send ONLY to linked games + same game • Uses your game's linked_game_ids field • Controlled partnerships • Curated send destinations Caching Implementation Best Practices Why Cache the Destinations API? • Performance: Instant send UI loading • Reliability: Works even if API is temporarily unavailable • Cost: Reduces API calls (game list doesn't change often) • User Experience: No loading delays when opening send screen Implementation Guidelines • Call /available-destinations once per day and cache locally • Use cached data to build send UI instantly • Refresh cache on app startup or manual refresh • Store in persistent storage (not just memory) • Handle cache miss gracefully with loading states • Show game icons and names from destinations data • Validate send amounts against min/max limits from response Fee Structure Default split (both tenants at 3.5%) Sending tenant fee 3.5% Receiving tenant fee 3.5% Network fee (Invo) 3.0% Total user-paid fee 10.0% Example send Send amount: 1,000 Gold Total fees (10%): -100 Gold Receiver gets: 900 Gold Per-tenant rate overrides Same policy as transfers: each tenant has a transfer_fee_percentage field (default 3.5%, range 0–10) that controls its kickback share on every send it participates in. Negotiated rates above 3.5% absorb from Invo's 3% slice; the user-paid total stays at exactly 10%. Read fee_breakdown from the API response or fee_total from the webhook for the actual numbers — don't recompute client-side. Security & Anti-Fraud Features 🔒 Phone-Based Claim Security Currency send claim codes are now locked to specific phone numbers. Only the receiver phone specified during initiation can redeem the claim code. • receiver_player_phone required at initiation • Claim codes can ONLY be redeemed by the specified phone number • Phone mismatch results in 403 Forbidden error • Prevents unauthorized claim code sharing and redemption SMS Verification • SMS PIN required to authorize sends • 10-minute expiration window • Maximum 3 attempts per PIN • Rate limiting on SMS requests • Phone-locked claim codes Fraud Prevention • Send velocity limits per player • Duplicate send detection • IP-based rate limiting • Failed attempt tracking and blocking Time Limits • SMS PIN: 10 minutes to verify • Claim code: 24 hours to claim • Expired sends return funds automatically • No funds lost due to expiration Player Protection • Funds reserved during verification • Automatic refunds on failure/expiration • Clear status tracking throughout process • SMS notifications at each step Rate Limits & Restrictions Current Limits (Launch Period) Destinations API • 100 requests per minute per IP • Should be cached for 24 hours • Call once daily at app startup Per Player Limits • 100 send initiations per hour • 35 SMS verifications per hour • 25 claim attempts per hour • 25 sends per hour (velocity limit) • 1,000,000 currency units per day (default, configurable) Per IP Address Limits • 300 initiations per hour • 175 verifications per hour • 125 claims per hour • 20 requests per minute (initiate-send burst limit) Note: These limits are generous during the initial launch period and may be adjusted based on usage patterns and security requirements. Currency Sends vs Cross-Game Transfers Currency Sends • Player-to-player: Direct recipient via phone number • Same or cross-game: Can send within game or to other games • Immediate notification: Claim code sent directly to receiver • Personal transactions: Perfect for gifting and player trades • Phone-based claiming: Receiver identified by phone number Cross-Game Transfers • Self-transfer: Moving your own currency between games • Cross-game only: Must be between different games • Manual claim sharing: Sender shares claim code manually • Portfolio management: Managing currency across your games • Game-based claiming: Claim in specific target game Send Status Definitions pending_pin_verification Currency send initiated, waiting for SMS PIN verification from sender. Funds are reserved. pending_claim SMS verified, claim code sent to receiver. Waiting for recipient to claim the currency. completed Currency send successfully claimed and completed. Currency credited to receiver. failed / expired Send failed verification, expired, or was cancelled. Funds returned to sender. Polling Send Status GET /api/currency-sends/<transaction_id>/status Retrieve the current state of a currency send Authentication & Access Include a game secret key in the request headers. Accessible by either the sending game or the receiving game on the send: X-Game-Secret-Key: your_game_secret_key_here Rate Limit 60 requests per minute per IP address. Suitable for light polling while a send is in flight. Use this to track a send through its lifecycle (e.g., after initiate, while waiting for the receiver to claim). The response shape varies with the current status — verification, claim, completion, and failure details are returned conditionally. Example Response (200 OK) { "status": "success", "transaction_id": "txn_send123abc456", "transaction_type": "currency_send", "transaction_status": "pending_claim", "verification_state": "approved", "amount": "500.00", "net_amount": "450.00", "fee_amount": "50.00", "created_at": "2024-06-24T15:00:00Z", "sending_game_id": "123456789012", "sending_game_name": "Adventure Quest", "receiving_game_id": "987654321098", "receiving_game_name": "Space Warriors", "currency_id": 1, "currency_name": "Gold", "order_id": "ord_send789def012", // Conditional — depends on transaction_status: // pending_pin_verification / pending_verification: "verification_info": { "sms_pin_expires_at": "2024-06-24T15:10:00Z" }, // pending_claim / verified: "claim_info": { "claim_code_expires_at": "2024-06-25T15:00:00Z" }, // completed: "completed_at": "2024-06-24T15:30:00Z", // present only when the send failed: "failure_reason": "..." } Field Description transaction_status Current send state (see Status Definitions above). verification_state 'awaiting' | 'approved' | 'completed' | 'expired' | 'failed' . Flips awaiting → approved when the sender clears verification (SMS or in-app); the field a waiting panel polls on. amount / net_amount / fee_amount Gross send amount, amount creditable on claim (after fees), and total fee. Decimal strings; may be null if not yet set. sending_game_id / sending_game_name The originating game. receiving_game_id / receiving_game_name The destination game. currency_id / currency_name Currency being sent. verification_info Present while awaiting SMS PIN verification — contains sms_pin_expires_at . claim_info Present while awaiting claim — contains claim_code_expires_at . completed_at Present once the send is completed. failure_reason Present only when the send failed.

---

## Send Destinations

URL: https://docs.invo.network/docs/send-available-destinations
Endpoint: POST /api/currency-sends/available-destinations

API documentation for finding available players to send currency to across games.

Currency Send Destinations API New API endpoint to get available currency send destinations. This supplements your existing currency send system by providing the list of games players can send currency to. No changes to existing APIs. Addition to Existing System • New API: /api/currency-sends/available-destinations • Existing APIs unchanged: /initiate-send , /verify-sms , /claim-currency • Optional integration: Use to improve UX, not required for sends to work • Backward compatible: Your current send implementation continues working POST /api/currency-sends/available-destinations Get games that players can send currency to Same Authentication Uses the same authentication as your existing currency send endpoints: X-Game-Secret-Key: your_game_secret_key_here Request Body { "source_game_id": "123456789012" } Response { "status": "success", "available_games": [...], "total_destinations": 5 } Integration Patterns Pattern 1: Add to Existing UI (Recommended) Call this API to populate your existing game selection dropdown. Your current send flow remains unchanged. Before: Hard-coded game list or manual game ID entry After: Dynamic game list from API, same send process Pattern 2: Pre-Send Validation Use the API response to validate send amounts against min/max limits before calling /initiate-send . Benefit: Prevent failed sends due to amount limits, better user feedback Pattern 3: Optional Caching (Performance) Cache the response for better performance. Call once daily and store locally. Optional: Only implement if you want instant UI loading Complete Response Example { "status": "success", "source_game_id": "123456789012", "source_game_name": "Adventure Quest", "source_game_icon": "https://cdn.invo.network/icons/adventure-quest.png", "source_currency_name": "Gold", "source_currency_icon": "https://cdn.invo.network/currency/gold.png", "universal_transfers": "yes", "transfer_mode": "universal", "available_games": [ { "game_id": "123456789012", "game_name": "Adventure Quest", "tenant_type": "game", "developer_name": "Your Studio", "publisher_name": "Your Publisher", "genre": "RPG", "platform": "PC", "game_status": "live", "game_icon": "https://cdn.invo.network/icons/adventure-quest.png", "game_poster": "https://cdn.invo.network/posters/adventure-quest.png", "game_url": "https://adventurequest.example.com", "game_description": "An epic fantasy RPG.", "currency_name": "Gold", "currency_symbol": "G", "currency_symbol_url": "https://cdn.invo.network/currency/gold.png", "minimum_transfer": "1.00", "maximum_transfer": null, "accepts_steam_origin_value": false }, { "game_id": "987654321098", "game_name": "Space Warriors", "tenant_type": "game", "developer_name": "Other Studio", "publisher_name": "Other Publisher", "genre": "Action", "platform": "Mobile", "game_status": "live", "game_icon": "https://cdn.invo.network/icons/space-warriors.png", "game_poster": "https://cdn.invo.network/posters/space-warriors.png", "game_url": "https://spacewarriors.example.com", "game_description": "Fast-paced space combat.", "currency_name": "Energy Credits", "currency_symbol": "EC", "currency_symbol_url": "https://cdn.invo.network/currency/energy-credits.png", "minimum_transfer": "5.00", "maximum_transfer": "1000.00", "accepts_steam_origin_value": true } ], "total_destinations": 2 // When transfer_mode is "linked", the response also includes: // "linked_game_ids": ["987654321098", "456789012345"] } Key Points • Same game included: Your own game appears for peer-to-peer sends • Transfer limits: Use minimum_transfer and maximum_transfer for validation • Game info: Display game_name and currency_symbol in UI • IDs for sending: Use game_id in your existing /initiate-send calls • Steam containment: accepts_steam_origin_value is true when the destination is a Steam-distributed title that can receive Steam-purchased currency — gray out non-Steam destinations for a player holding Steam-purchased currency. When your source game is not a Steam title, Steam-distributed destinations are omitted from available_games entirely (non-Steam currency can't enter Steam titles). Applies only to ecosystems with Steam-distributed titles. Minimal Integration Examples Unity Add to Your Existing Unity Code // Add this new function to your existing currency send system public IEnumerator GetAvailableDestinations(Action<string> onSuccess, Action<string> onError) { string url = "https://invo.network/api/currency-sends/available-destinations"; var requestData = new { source_game_id = "123456789012" // Your game ID }; string jsonBody = JsonUtility.ToJson(requestData); using (UnityWebRequest request = new UnityWebRequest(url, "POST")) { byte[] bodyRaw = System.Text.Encoding.UTF8.GetBytes(jsonBody); request.uploadHandler = new UploadHandlerRaw(bodyRaw); request.downloadHandler = new DownloadHandlerBuffer(); // Use your existing secret key request.SetRequestHeader("X-Game-Secret-Key", "your_game_secret_key_here"); request.SetRequestHeader("Content-Type", "application/json"); yield return request.SendWebRequest(); if (request.result == UnityWebRequest.Result.Success) { onSuccess?.Invoke(request.downloadHandler.text); } else { onError?.Invoke(request.error + ": " + request.downloadHandler.text); } } } // Your existing InitiateCurrencySend function stays exactly the same! // Just use the game IDs from the destinations response C++ Add to Your Existing C++ Code // Add this new function to your existing currency send system #include <curl/curl.h> #include <json/json.h> struct APIResponse { std::string data; }; static size_t WriteCallback(void *contents, size_t size, size_t nmemb, APIResponse *response) { size_t totalSize = size * nmemb; response->data.append((char*)contents, totalSize); return totalSize; } bool GetAvailableDestinations(const std::string& source_game_id, const std::string& secret_key, std::string& response) { CURL *curl; CURLcode res; APIResponse apiResponse; curl = curl_easy_init(); if(curl) { // Set URL curl_easy_setopt(curl, CURLOPT_URL, "https://invo.network/api/currency-sends/available-destinations"); // Create JSON request body Json::Value requestData; requestData["source_game_id"] = source_game_id; Json::StreamWriterBuilder builder; std::string jsonString = Json::writeString(builder, requestData); // Set headers struct curl_slist *headers = NULL; std::string authHeader = "X-Game-Secret-Key: " + secret_key; headers = curl_slist_append(headers, "Content-Type: application/json"); headers = curl_slist_append(headers, authHeader.c_str()); curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers); // Set POST data curl_easy_setopt(curl, CURLOPT_POSTFIELDS, jsonString.c_str()); // Set callback for response curl_easy_setopt(curl, CURLOPT_WRITEFUNCTION, WriteCallback); curl_easy_setopt(curl, CURLOPT_WRITEDATA, &apiResponse); // Perform request res = curl_easy_perform(curl); // Cleanup curl_slist_free_all(headers); curl_easy_cleanup(curl); if(res == CURLE_OK) { response = apiResponse.data; return true; } } return false; } // Usage example: void PopulateGameDropdown() { std::string response; if(GetAvailableDestinations("123456789012", "your_game_secret_key_here", response)) { Json::Value root; Json::Reader reader; if(reader.parse(response, root)) { const Json::Value& available_games = root["available_games"]; for(const auto& game : available_games) { std::string game_id = game["game_id"].asString(); std::string game_name = game["game_name"].asString(); std::string currency_symbol = game["currency_symbol"].asString(); // Add to your existing dropdown/UI AddGameToDropdown(game_id, game_name + " (" + currency_symbol + ")"); } } } } // Your existing InitiateCurrencySend function stays exactly the same! Godot Add to Your Existing Godot Code # Add this new function to your existing currency send system extends Node var http_request: HTTPRequest func _ready(): http_request = HTTPRequest.new() add_child(http_request) http_request.request_completed.connect(_on_destinations_response) func get_available_destinations(source_game_id: String, secret_key: String): var url = "https://invo.network/api/currency-sends/available-destinations" var headers = [ "Content-Type: application/json", "X-Game-Secret-Key: " + secret_key ] var request_data = { "source_game_id": source_game_id } var json_string = JSON.stringify(request_data) http_request.request(url, headers, HTTPClient.METHOD_POST, json_string) func _on_destinations_response(result: int, response_code: int, headers: PackedStringArray, body: PackedByteArray): if response_code == 200: var json = JSON.new() var parse_result = json.parse(body.get_string_from_utf8()) if parse_result == OK: var response_data = json.data if response_data.status == "success": populate_game_dropdown(response_data.available_games) else: print("API Error: ", response_data.message) else: print("JSON Parse Error") else: print("HTTP Error: ", response_code) func populate_game_dropdown(available_games: Array): var dropdown = get_node("GameDropdown") # Your existing dropdown dropdown.clear() for game in available_games: var game_id = game.game_id var game_name = game.game_name var currency_symbol = game.currency_symbol var display_text = game_name + " (" + currency_symbol + ")" dropdown.add_item(display_text) dropdown.set_item_metadata(dropdown.get_item_count() - 1, game_id) # Usage example: func _on_refresh_games_pressed(): get_available_destinations("123456789012", "your_game_secret_key_here") # Your existing initiate_currency_send function stays exactly the same! # Just use the game IDs from the dropdown metadata Migration Strategy Phase 1: Add Destinations API (Optional) • Add the new destinations endpoint call • Use response to populate existing game selection UI • Keep all existing send logic unchanged Phase 2: Add Validation (Optional) • Use min/max amounts from destinations response • Validate amounts before calling your existing send APIs • Provide better user feedback Phase 3: Add Caching (Optional) • Cache destinations response for 24 hours • Improve performance by avoiding repeated API calls • Add manual refresh option Benefits of Integration User Experience • Dynamic game list instead of hard-coded options • Real-time transfer limits and validation • Clear game names and currency info • Reduced failed sends due to invalid destinations Developer Benefits • No manual game list maintenance • Automatic new game discovery • Centralized transfer policy management • Better error prevention Performance • Optional caching for instant UI loading • Reduced failed API calls • Better network efficiency • Graceful fallback options Ecosystem • Automatic support for new games • Respect for universal vs linked transfer modes • Same-game peer-to-peer support • Future-proof implementation Frequently Asked Questions Do I need to change my existing send APIs? No. Your existing /initiate-send , /verify-sms , and /claim-currency endpoints work exactly the same. This is just an additional API to get destination information. Is this API required for sends to work? No, it's optional. Your current currency sends will continue working. This API just helps improve the user experience by providing dynamic game lists and validation data. How often should I call this API? Once per day is sufficient. Game lists don't change frequently. You can cache the response and refresh daily, or call it each time a player opens the send UI (but caching is more efficient). Will my own game appear in the destinations list? Yes, your own game appears in the list to support peer-to-peer currency sends within the same game. Use the same receiving_game_id as your source game for same-game sends. What happens if the destinations API is unavailable? Your existing send functionality continues working. You can implement fallback logic (cached data, default game list, or manual game ID entry) while the destinations API is unavailable.

---

## Initiate Player Send

URL: https://docs.invo.network/docs/initiate-send
Endpoint: POST /api/currency-sends/initiate-send

Initiate player-to-player currency sends using Invo Network Send API.

Initiate Player Currency Send Start a secure currency send to another player via their phone number. This endpoint supports both peer-to-peer sends within your game and cross-game currency sends to other games in the Invo ecosystem. Currency Send Types Peer-to-Peer Sends Send currency to another player within your own game by setting receiving_game_id to your game's ID. • Player-to-player transactions • Marketplace purchases • Gifting between friends • In-game services and tips Cross-Game Sends Send currency to players in other games by setting receiving_game_id to a different game's ID. • Cross-game community building • Ecosystem-wide interactions • Portfolio value distribution • Multi-game rewards POST /api/currency-sends/initiate-send Initiates a player-to-player currency send with SMS verification Security Requirement This endpoint must only be called from your secure game server. Never call it directly from a game client. Authentication Required All requests must include your game's secret key in the request headers: X-Game-Secret-Key: your_game_secret_key_here Policy Requirements For cross-game sends, your game's transfer policy determines which destinations are allowed: • Universal Transfers: Can send to any live game in the ecosystem • Linked Transfers: Can only send to games in your linked_game_ids list • Testing Games: Cannot send to or from games in testing status Request Body Parameters Parameter Type Required Description client_request_id string Yes Unique ID for this send attempt (prevents duplicates) sender_player_name string Yes Display name of the player sending the currency sender_player_email string Yes Email address of the sending player sender_player_phone string Yes Phone number for SMS verification (format: +1234567890) receiver_player_email string Yes 🔒 SECURITY: Receiver's email address. Required as of 2026-05-07 so the phone-share approval gate can fire at initiate time, before any transaction is staged. If this email is new on the network and the supplied phone is already on file under a different email, the response is a 409 PHONE_SHARE_APPROVAL_REQUIRED with an SMS auto-sent to the existing phone owner. receiver_player_phone string Yes 🔒 SECURITY: Receiver's phone number. Claim code can ONLY be redeemed by this number (format: +1234567890) receiving_game_id integer Yes ID of the game where currency will be received (same ID for peer-to-peer) amount string Yes Amount to send (as decimal string, e.g. "100.50") Implementation Examples Unity Unity C# Currency Send Initiation // This function MUST be called on your secure server, NOT the client. public IEnumerator InitiateCurrencySend(string clientRequestId, string senderName, string senderEmail, string senderPhone, string receiverEmail, string receiverPhone, int receivingGameId, string amount, Action<string> onSuccess, Action<string> onError) { string url = "https://invo.network/api/currency-sends/initiate-send"; var requestData = new { client_request_id = clientRequestId, sender_player_name = senderName, sender_player_email = senderEmail, sender_player_phone = senderPhone, receiver_player_email = receiverEmail, // REQUIRED 2026-05-07: gates phone-share check at initiate receiver_player_phone = receiverPhone, receiving_game_id = receivingGameId, // Same as your game ID for peer-to-peer amount = amount }; string jsonBody = JsonUtility.ToJson(requestData); using (UnityWebRequest request = new UnityWebRequest(url, "POST")) { byte[] bodyRaw = System.Text.Encoding.UTF8.GetBytes(jsonBody); request.uploadHandler = new UploadHandlerRaw(bodyRaw); request.downloadHandler = new DownloadHandlerBuffer(); request.SetRequestHeader("X-Game-Secret-Key", "your_game_secret_key_here"); request.SetRequestHeader("Content-Type", "application/json"); yield return request.SendWebRequest(); if (request.result == UnityWebRequest.Result.Success) { onSuccess?.Invoke(request.downloadHandler.text); } else { onError?.Invoke(request.error + ": " + request.downloadHandler.text); } } } Unreal Unreal C++ Currency Send Initiation // This function MUST be called on your secure server. void AYourGameMode::InitiateCurrencySend(const FString& ClientRequestId, const FString& SenderName, const FString& SenderEmail, const FString& SenderPhone, const FString& ReceiverEmail, const FString& ReceiverPhone, int32 ReceivingGameId, const FString& Amount) { TSharedPtr<FJsonObject> RequestObj = MakeShareable(new FJsonObject); RequestObj->SetStringField("client_request_id", ClientRequestId); RequestObj->SetStringField("sender_player_name", SenderName); RequestObj->SetStringField("sender_player_email", SenderEmail); RequestObj->SetStringField("sender_player_phone", SenderPhone); RequestObj->SetStringField("receiver_player_email", ReceiverEmail); // REQUIRED 2026-05-07: gates phone-share check at initiate RequestObj->SetStringField("receiver_player_phone", ReceiverPhone); RequestObj->SetNumberField("receiving_game_id", ReceivingGameId); RequestObj->SetStringField("amount", Amount); FString RequestBody; TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&RequestBody); FJsonSerializer::Serialize(RequestObj.ToSharedRef(), Writer); TSharedRef<IHttpRequest> Request = FHttpModule::Get().CreateRequest(); Request->SetURL("https://invo.network/api/currency-sends/initiate-send"); Request->SetVerb("POST"); Request->SetHeader("X-Game-Secret-Key", "your_game_secret_key_here"); Request->SetHeader("Content-Type", "application/json"); Request->SetContentAsString(RequestBody); Request->OnProcessRequestComplete().BindUObject(this, &AYourGameMode::OnSendInitiated); Request->ProcessRequest(); } Godot Godot GDScript Currency Send Initiation # This function MUST be called on your secure server. func initiate_currency_send(client_request_id: String, sender_name: String, sender_email: String, sender_phone: String, receiver_email: String, receiver_phone: String, receiving_game_id: int, amount: String): var url = "https://invo.network/api/currency-sends/initiate-send" var headers = [ "X-Game-Secret-Key: your_game_secret_key_here", "Content-Type: application/json" ] var body = { "client_request_id": client_request_id, "sender_player_name": sender_name, "sender_player_email": sender_email, "sender_player_phone": sender_phone, "receiver_player_email": receiver_email, # REQUIRED 2026-05-07: gates phone-share check at initiate "receiver_player_phone": receiver_phone, "receiving_game_id": receiving_game_id, # Same as your game ID for peer-to-peer "amount": amount } http_request.request(url, headers, HTTPClient.METHOD_POST, JSON.stringify(body)) Request & Response Examples Example: Peer-to-Peer Send (Same Game) POST /api/currency-sends/initiate-send Content-Type: application/json X-Game-Secret-Key: your_game_secret_key_here { "client_request_id": "p2p_send_12345_20240624", "sender_player_name": "PlayerOne", "sender_player_email": "player1@example.com", "sender_player_phone": "+1234567890", "receiver_player_email": "recipient@example.com", "receiver_player_phone": "+1987654321", "receiving_game_id": 123456789012, "amount": "500.00" } // Note: receiving_game_id matches your own game ID for peer-to-peer sends // Note: receiver_player_email is REQUIRED as of 2026-05-07 — required so the // phone-share approval gate can fire at initiate time, before any // transaction is staged. See PHONE_SHARE_APPROVAL_REQUIRED docs. Example: Cross-Game Send POST /api/currency-sends/initiate-send Content-Type: application/json X-Game-Secret-Key: your_game_secret_key_here { "client_request_id": "cross_send_67890_20240624", "sender_player_name": "PlayerOne", "sender_player_email": "player1@example.com", "sender_player_phone": "+1234567890", "receiver_player_email": "recipient@example.com", "receiver_player_phone": "+1987654321", "receiving_game_id": 987654321098, "amount": "250.00" } // Note: receiving_game_id is different from your game ID for cross-game sends Watch for HTTP 202 — guardian approval pending If the sending account is flagged as a minor on Invo, this endpoint returns 202 Accepted instead of 201, with a guardian_approval block. The send is held until the guardian replies YES or NO via SMS within 15 minutes. This is the standard integration pattern going forward — handle it defensively on every initiate call ; you can't detect minor status from the partner side. Full contract: Guardian Approval . Success Response (201 Created) { "status": "success", "message": "Currency send initiated. Please verify with the SMS PIN sent to your phone.", "transaction_id": "txn_send123abc456", "order_id": "ord_send789def012", "new_balance": "9500.00", "currency_name": "Gold", "verification_method": "sms", "verification_expires_at": "2026-01-01T12:10:00Z", "send_details": { "sending_game": "Adventure Quest", "receiving_game": "Space Warriors", "receiving_game_id": "987654321098", "currency": "Gold", "currency_id": 1, "amount_initiated": "500.00", "fees_preview": { "total_fee": "50.00", "source_rate_pct": "3.5", "target_rate_pct": "3.5", "sending_game_fee": "17.50", "receiving_game_fee": "17.50", "platform_fee": "15.00", "net_amount": "450.00" }, "receiver_phone": "+1987654321", "send_type": "cross_game", "transfer_policy": { "source_universal_transfers": "yes", "policy_applied": "universal", "target_in_linked_list": null } }, "verification_required": { "phone_number_masked": "******7890", "pin_expires_in_minutes": 10 } } Top-level new_balance is the canonical post-write balance — the sender's available balance after the send amount has been reserved. Display this value rather than recomputing it client-side. fees_preview also includes source_rate_pct and target_rate_pct . verification_method is 'in_app' | 'sms' — it is 'sms' for every game today and whenever the SMS PIN was sent. It is 'in_app' only when in-app verification is enabled for your game and the sender is enrolled (proactive PIN suppressed) — in that case show the in-app approval panel and call POST /api/sdk/send/ {id} /approve instead of the SMS-code screen. verification_expires_at is the ISO verification window. Pending Guardian Approval (202 Accepted) { "status": "pending_guardian_approval", "message": "Currency send initiated. SMS PIN sent to your phone, but verification is held until the guardian on file approves via SMS.", "transaction_id": "txn_send123abc456", "order_id": "ord_send789def012", "guardian_approval": { "approval_id": "1f2a8c0d-...", "state": "pending", "expires_at": "2026-05-04T22:15:00+00:00", "poll_endpoint": "/api/transactions/txn_send123abc456/approval-status" }, "send_details": { /* same as 201 success */ }, "verification_required": { /* same as 201 success */ } } Show a "waiting for parent approval" UI and poll poll_endpoint every 5–10s. See Guardian Approval for the full state machine. Error Response - Phone-Share Approval Required (409 Conflict) { "status": "error", "error_code": "PHONE_SHARE_APPROVAL_REQUIRED", "message": "This phone number is already linked to another Invo account. The existing phone owner must approve via SMS before this email can also use this phone.", "phone": "+15551234567", "requesting_email": "bob@example.com", "existing_account_hints": ["al***@example.com"], "next_endpoint": "/api/wallet/phone-share/initiate", "approval_id": "1f2a8c0d-...", "expires_at": "2026-05-04T22:25:00+00:00", "code_sent": true, "already_approved": false } Fires when the supplied phone is already on file with a different email. Same contract for game-developer SDK integrations and platform-tier partners. The OTP SMS is auto-sent — have the existing phone owner read the SMS, then call POST /api/wallet/phone-share/approve with the approval_id from the body and the 6-digit OTP, then retry the original call. Only call /phone-share/initiate manually if code_sent: false . Match on error_code , not message text . Initiate-time gate (since 2026-05-07): the gate now fires at /initiate-send as well as /claim-currency . Previously the conflict was only detected at claim time, after the sender had reserved funds and received an SMS-PIN. Now the 409 fires at initiate, before any Transaction , TransferPin , or OrderBook row is created. Net effect: zero side effects until the existing phone owner has approved. If already_approved: true : auto-retry the original action immediately, do not show the OTP entry UI. The flag means a concurrent approval landed between gate-check and response — the pair is approved on the backend; the gate fired in a brief race window. The retry will succeed. One retry, no loops. Anti-abuse fields (optional, present only when triggered): cooldown_seconds appears when a fresh OTP for the same (phone, email) was minted less than 30s ago — no new SMS is sent , the previous code on the user's phone is still valid, and the included approval_id is the same row. Show the OTP entry panel as normal; do not show "code not sent" copy and do not auto-call /phone-share/initiate until the cooldown elapses. rate_limited: true + retry_after_seconds appear when this phone has hit the platform-wide 40-OTP-per-hour cap — no SMS sent, no approval_id returned, surface "please wait before requesting another code." Three valid response paths the existing phone owner can choose between: Approve via UI: type the 6-digit code into your UI → call POST /api/wallet/phone-share/approve with { approval_id, otp } . Approve via SMS reply: text the code (or YES <code> ) back from their phone. Invo's inbound webhook stamps the approval server-side. Reject (new, 2026-05-14): either call POST /api/wallet/phone-share/reject with { approval_id, otp } from your UI, OR reply NO (or NO <code> ) by SMS from the phone on file. Rejected rows are terminal — the requesting email must re-trigger a fresh request to retry. A subsequent /phone-share/initiate for the same pair creates a new approval row. If a user takes either SMS path, your client gets no direct callback — poll GET /api/wallet/phone-share/status?phone=...&email=... every 3–5s while your panel is open. Auto-retry the original action when approved: true ; surface a clear rejection message and offer a "try again" affordance if the user reports a NO reply (the status endpoint returns approved: false for both pending and rejected states — distinguishable only by the existence of a newer pending row after a fresh initiate). Error Response - Policy Violation (403 Forbidden) { "status": "error", "message": "Currency send not allowed: Receiving game 'Space Warriors' (ID: 987654321098) is not in the linked games list for sending game 'Adventure Quest'. Linked games: [123456789012, 456789012345]", "error_code": "CURRENCY_SEND_POLICY_VIOLATION" } Error Response - Testing Game (403 Forbidden) { "status": "error", "message": "Currency sends are not allowed to games in testing status. Receiving game 'Test Game' must be live to receive currency sends." } Error Response - Steam Value Not Transferable (409 Conflict) { "status": "error", "error_code": "STEAM_VALUE_NON_TRANSFERABLE", "message": "Currency purchased through Steam can only be used within Steam titles and can't be transferred here.", "transferable_max": "150.00", "steam_origin_amount": "350.00" } Fires when the sender tries to move more than their non-Steam-origin balance to a non-Steam destination. Currency a player buys through Steam stays within Steam-distributed titles. transferable_max is how much they can still send to this destination (their non-Steam portion); steam_origin_amount is the Steam-purchased portion that is locked to Steam titles. Offer to retry at or below transferable_max . Match on error_code , not message text. These two Steam-containment errors only appear when a Steam-distributed title is on one side of the send — a per-title setting configured by the platform. Most integrations never see them. Error Response - Non-Steam Value Into Steam Title (409 Conflict) { "status": "error", "error_code": "NON_STEAM_VALUE_INTO_STEAM_BLOCKED", "message": "This title only accepts currency from other Steam titles." } Fires when sending from a non-Steam game into a Steam-distributed title — non-Steam currency can't enter Steam titles. Match on error_code , not message text. Error Response - Rate Limited (429 Too Many Requests) { "error": "velocity_limit_exceeded", "message": "Hourly currency send limit of 25 sends exceeded. Please try again later." } What Happens After Initiation SMS PIN Sent to Sender The sending player receives an SMS with a 6-digit verification PIN at their phone number. The message format is: "Your Invo currency send from Adventure Quest to Space Warriors verification code is 123456. Valid for 10 minutes. Our employees will never ask you for this code." Funds Reserved The send amount is immediately reserved from the sender's available balance. This ensures the funds are secured for the send but not yet deducted. If the send fails or expires, the reserved amount is automatically returned to their available balance. Next Steps The sender has 10 minutes to verify the SMS PIN using the /verify-sms endpoint. After verification, a claim code will be automatically sent to the receiver's phone number. Validation Rules & Restrictions Phone Number Format • Both sender and receiver phones must start with country code (e.g., +1 for US) • Must be 10-15 digits total after country code • Only digits allowed after the + symbol • Examples: +1234567890, +441234567890 Send Amount Limits • Must be greater than currency minimum (usually 0.01) • Must not exceed currency maximum (if set by game) • Must not exceed sender's available balance • Daily send limit: 1,000,000 currency units per player (default, admin-configurable) • Hourly send limit: 25 sends per player Game Status Requirements • Sending Game: Must be in 'live' status (not 'testing') • Receiving Game: Must be in 'live' status (not 'testing') • Peer-to-Peer: Always allowed within the same live game • Cross-Game: Requires both games to be live and policy-compliant Transfer Policy Requirements • Universal Transfers (universal_transfers: "yes"): Can send to any live game • Linked Transfers (universal_transfers: "no"): Can only send to games in linked_game_ids • Sending game must have allows_outgoing_transfers enabled • Target game must be found in ecosystem Duplicate Prevention • client_request_id must be unique per game • Rapid identical sends (same amount/receiver) are blocked • Rate limiting prevents spam attempts • Velocity limits prevent excessive send activity Common Error Scenarios HTTP 400 - Bad Request • Missing required fields • Invalid phone number format (sender or receiver) • Invalid amount (negative, too large, etc.) • Receiving game not found • Insufficient balance HTTP 403 - Forbidden • Game in testing status (sender or receiver) • Transfer policy violation (not in linked games) • Outgoing transfers not allowed • Universal transfers disabled and target not linked HTTP 409 - Conflict • Duplicate client_request_id • Send already initiated or processed HTTP 429 - Too Many Requests • Player exceeded hourly send initiation limit (100/hour) • IP address exceeded rate limits • Velocity limits exceeded — this is a separate control (25 sends/hour per player) and returns velocity_limit_exceeded • Rapid identical send detection HTTP 500 - Server Error • SMS service unavailable • Database connectivity issues • Internal system errors Implementation Best Practices User Experience • Use the /available-destinations endpoint to get valid receiving games • Validate phone numbers before submitting • Show send fee preview before confirmation • Display clear error messages for validation failures • Provide phone number formatting hints • Show receiving game name clearly in send UI • Distinguish between peer-to-peer and cross-game sends in UI Error Handling • Parse API error responses for user-friendly messages • Handle rate limiting with appropriate retry delays • Implement exponential backoff for server errors • Log all send attempts for debugging and monitoring • Provide fallback options when services are unavailable • Handle policy violations gracefully with clear explanations Security • Always call from secure server, never from game client • Validate all input data before API submission • Use unique client_request_id for each send • Implement proper timeout handling • Never expose game secret keys in client code • Validate receiving_game_id against allowed destinations Send Flow Management • Save transaction_id for subsequent verification calls • Display SMS PIN entry UI immediately after success • Show countdown timer for PIN expiration (10 minutes) • Provide option to cancel send before verification • Update sender balance display to show reserved amount • Inform sender that receiver will be notified via SMS • Handle both peer-to-peer and cross-game send flows

---

## Verify Send SMS

URL: https://docs.invo.network/docs/verify-send-sms
Endpoint: POST /api/currency-sends/verify-sms

Verify player-to-player sends using SMS verification for secure currency gifting.

Verify Currency Send SMS PIN Verify the SMS PIN to authorize a currency send. This endpoint validates the PIN sent to the sender's phone and, upon success, automatically sends the claim code to the receiver via SMS. POST /api/currency-sends/verify-sms Verifies the SMS PIN and sends claim code to receiver Authentication Required Must include the same game secret key used to initiate the send: X-Game-Secret-Key: your_game_secret_key_here Request Body Parameters Parameter Type Required Description transaction_id string Yes Transaction ID returned from initiate-send sms_pin string Yes 6-digit PIN received via SMS SMS PIN Requirements PIN Format • 6-digit numeric code • Case-sensitive (numbers only) • Unique per send attempt • One-time use only Time Limits • PIN expires in 10 minutes • Maximum 3 verification attempts • Failed attempts count toward rate limits • Expired PINs cannot be reused Implementation Examples Unity Unity C# SMS Verification // This function MUST be called on your secure server, NOT the client. public IEnumerator VerifySendSMSPin(string transactionId, string smsPin, Action<string> onSuccess, Action<string> onError) { string url = "https://invo.network/api/currency-sends/verify-sms"; var requestData = new { transaction_id = transactionId, sms_pin = smsPin }; string jsonBody = JsonUtility.ToJson(requestData); using (UnityWebRequest request = new UnityWebRequest(url, "POST")) { byte[] bodyRaw = System.Text.Encoding.UTF8.GetBytes(jsonBody); request.uploadHandler = new UploadHandlerRaw(bodyRaw); request.downloadHandler = new DownloadHandlerBuffer(); request.SetRequestHeader("X-Game-Secret-Key", "your_game_secret_key_here"); request.SetRequestHeader("Content-Type", "application/json"); yield return request.SendWebRequest(); if (request.result == UnityWebRequest.Result.Success) { onSuccess?.Invoke(request.downloadHandler.text); } else { onError?.Invoke(request.error + ": " + request.downloadHandler.text); } } } Unreal Unreal C++ SMS Verification // This function MUST be called on your secure server. void AYourGameMode::VerifySendSMSPin(const FString& TransactionId, const FString& SMSPin) { TSharedPtr<FJsonObject> RequestObj = MakeShareable(new FJsonObject); RequestObj->SetStringField("transaction_id", TransactionId); RequestObj->SetStringField("sms_pin", SMSPin); FString RequestBody; TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&RequestBody); FJsonSerializer::Serialize(RequestObj.ToSharedRef(), Writer); TSharedRef<IHttpRequest> Request = FHttpModule::Get().CreateRequest(); Request->SetURL("https://invo.network/api/currency-sends/verify-sms"); Request->SetVerb("POST"); Request->SetHeader("X-Game-Secret-Key", "your_game_secret_key_here"); Request->SetHeader("Content-Type", "application/json"); Request->SetContentAsString(RequestBody); Request->OnProcessRequestComplete().BindUObject(this, &AYourGameMode::OnSendSMSVerified); Request->ProcessRequest(); } Godot Godot GDScript SMS Verification # This function MUST be called on your secure server. func verify_send_sms_pin(transaction_id: String, sms_pin: String): var url = "https://invo.network/api/currency-sends/verify-sms" var headers = [ "X-Game-Secret-Key: your_game_secret_key_here", "Content-Type: application/json" ] var body = { "transaction_id": transaction_id, "sms_pin": sms_pin } http_request.request(url, headers, HTTPClient.METHOD_POST, JSON.stringify(body)) Request & Response Examples Example Request POST /api/currency-sends/verify-sms Content-Type: application/json X-Game-Secret-Key: your_game_secret_key_here { "transaction_id": "txn_send123abc456", "sms_pin": "123456" } Guardian-approval-aware responses If the original send was initiated by a minor account, this endpoint may return: 202 GUARDIAN_APPROVAL_PENDING — guardian hasn't replied yet. The same call succeeds normally once approval lands; just keep polling. 410 GUARDIAN_APPROVAL_REJECTED or GUARDIAN_APPROVAL_EXPIRED — terminal. Show a clear message; user must re-initiate. Full state machine: Guardian Approval . Success Response (200 OK) { "status": "success", "message": "SMS verification successful. A claim code has been sent to the receiver.", "transaction_id": "txn_send123abc456", "claim_code": "KJMRS-47281", "new_balance": "750.00", "claim_instructions": { "message": "Claim code has been sent to the receiver via SMS.", "receiving_game_id": "42", "receiving_game_name": "Space Warriors", "claim_code_expires_at": "2024-06-25T14:30:00Z", "receiver_notified": true }, "send_summary": { "amount_sent": "500.00", "net_amount_for_claim": "450.00", "fees_deducted": "50.00", "sender_current_available_balance": "750.00" }, "order_id": "ord_send789def012" } Top-level new_balance is the canonical post-write balance — the sender's available balance, already debited by the reservation at initiate-send. Display this value rather than recomputing it client-side. Error Response - Invalid PIN (400 Bad Request) { "status": "error", "message": "Invalid SMS PIN.", "attempts_remaining": 2 } Error Response - Expired PIN (400 Bad Request) { "status": "error", "message": "SMS PIN is not valid: PIN expired." } Error Response - Rate Limited (429 Too Many Requests) { "error": "sms_verification_blocked", "message": "Too many SMS verification attempts. Please try again in 1 hour.", "retry_after": 3600 } Resend Verification PIN POST /api/currency-sends/resend-pin Re-sends the same still-valid PIN if the first SMS didn't arrive If the sender never received the first SMS, you can re-queue the same verification PIN for delivery. This does not generate a new PIN — the original code and its expiry are unchanged. Once the PIN has expired, re-initiate the send instead. Authentication Required Uses the same game secret key as initiate and verify: X-Game-Secret-Key: your_game_secret_key_here Request Body Parameters Parameter Type Required Description transaction_id string Yes Transaction ID returned from initiate-send. No sms_pin is sent — the original PIN is re-used. Example Request POST /api/currency-sends/resend-pin Content-Type: application/json X-Game-Secret-Key: your_game_secret_key_here { "transaction_id": "txn_send123abc456" } Response Codes Status Body Meaning 200 { "status": "resent" } The same PIN was re-queued for delivery. 429 { "error": "resend_cooldown", "retry_after": <seconds> } Requested too soon. Wait retry_after seconds before retrying (cooldown is 30s). 400 { "error": "pin_expired", "message": "Start a new transfer." } The PIN has already expired. No new PIN is minted — re-initiate the send instead. 400 Wrong state / missing field Send is not pending verification, or transaction_id is missing. 404 Not found Transaction not found, or it belongs to another game. 401 Unauthorized Bad or missing X-Game-Secret-Key . 503 { "error": "resend_unavailable" } Resend may be unavailable in some environments (e.g. sandbox today). Fall back to re-initiating the send. Recommended integrator flow PIN not received and not yet expired → call resend-pin (respect the 30s cooldown / retry_after ). On pin_expired or resend_unavailable (503) → re-initiate the send. Rate Limiting • 10 resends per hour per transaction • 60 resends per hour per source IP • Separate from the verify-sms rate limits • 30-second cooldown between consecutive resends What Happens After Successful Verification Claim Code Generated & Sent A unique claim code is generated and automatically sent via SMS to the receiver's phone number provided during send initiation. "You have received 450.00 Gold from PlayerOne. Claim code: KJMRS-47281. Use this in Space Warriors. Expires in 24 hours." Send Status Updated The send status changes from "pending_pin_verification" to "pending_claim". The funds remain reserved in the sender's account until the send is either claimed or expires. 24-Hour Claim Window The receiver has 24 hours to claim the currency using the claim code. If not claimed within this time, the send expires and the net amount (minus fees) is automatically returned to the sender's balance. Automatic Receiver Notification How Receivers Are Notified Unlike cross-game transfers where the sender manually shares the claim code, currency sends automatically notify the receiver via SMS. This creates a seamless experience for player-to-player transactions. SMS Content Includes: • Amount and currency received • Sender's display name • Unique claim code • Target game name for claiming • 24-hour expiration notice Note: The receiver doesn't need to have an account in the receiving game beforehand. If they don't exist as a player, a new account will be automatically created when they claim the currency. Security Features PIN Protection • Hashed storage - PINs never stored in plain text • Limited attempts - Maximum 3 verification tries • Time-based expiry - 10 minute validity window • One-time use - PIN becomes invalid after successful verification Rate Limiting • 35 verification attempts per hour per player • 20 attempts per minute per transaction • 175 attempts per hour per IP address • Failed attempts trigger progressive blocking Fraud Detection • SMS verification spam detection • Invalid PIN attempt tracking • IP-based suspicious activity monitoring • Automatic blocking for repeated failures Transaction Integrity • Funds remain reserved during verification • Automatic cleanup of expired transactions • Comprehensive audit trail • Circuit breaker for service protection Common Error Scenarios HTTP 400 - Bad Request • Invalid SMS PIN: PIN doesn't match or has wrong format • PIN expired: More than 10 minutes have passed since initiation • Max attempts reached: 3 incorrect PIN attempts used up • Missing parameters: transaction_id or sms_pin not provided • Wrong send state: Send not in pending_pin_verification status HTTP 404 - Not Found • Transaction not found: Invalid transaction_id or wrong game • Unauthorized access: Game secret key doesn't match send source HTTP 429 - Too Many Requests • SMS verification spam: Too many verification attempts from player • Transaction rate limit: Too many attempts for specific transaction • IP rate limit: Too many requests from the same network • Invalid PIN blocking: Player blocked due to repeated invalid PINs HTTP 500 - Server Error • Database connectivity: Temporary database issues • SMS service error: Unable to send claim code to receiver • Circuit breaker open: Service temporarily unavailable Implementation Best Practices User Experience • Display remaining attempts when PIN verification fails • Show countdown timer for PIN expiration • Provide clear error messages for different failure scenarios • If the PIN didn't arrive but hasn't expired, use resend-pin to re-send the same code; only re-initiate the send once the PIN has expired • Show receiver notification status (SMS sent automatically) Error Handling • Parse error responses to show appropriate user messages • Handle rate limiting with retry logic and user feedback • Implement exponential backoff for server errors • Log all API responses for debugging and monitoring • Provide clear guidance when SMS delivery fails Security • Never log or store SMS PINs in your application • Validate PIN format on client side before sending • Clear PIN input fields after submission • Use HTTPS for all API communications • Implement proper session management Send Completion • Inform sender that receiver has been automatically notified • Display claim code for sender's reference (optional) • Show receiving game name and expiration time clearly • Update sender's balance to reflect reserved amount • Provide send tracking/history functionality

---

## Claim Sent Currency

URL: https://docs.invo.network/docs/claim-currency
Endpoint: POST /api/currency-sends/claim-currency

API documentation for claiming currency sent by other players across games.

Claim Sent Currency Complete a currency send by claiming the funds with a claim code received via SMS. This endpoint validates the claim code, creates or updates the receiver player, and credits the sent currency to their balance. POST /api/currency-sends/claim-currency Claims a currency send using the provided claim code Authentication Required Must include the receiving game's secret key (where the funds will be received): X-Game-Secret-Key: receiving_game_secret_key_here Rate Limits • 25 per hour per receiving player (keyed on receiver_player_email ) • 15 per minute per claim code • 125 per hour per IP address Exceeding any limit returns 429 Too Many Requests . These are separate from the CLAIM_LOCKED failed-attempt lockout documented below. Request Body Parameters Parameter Type Required Description claim_code string Yes Claim code received via SMS. Format is ABCDE-12345 — 5 uppercase letters (excluding O ) + hyphen + 5 digits (excluding 0 ). Total 11 characters. Case-sensitive. receiver_player_name string Yes Display name of the player claiming the currency receiver_player_email string Yes Email address of the receiving player receiver_player_phone string (E.164) Yes 🔒 SECURITY: Phone of the receiving player. MUST match the receiver_player_phone sent at initiation. Strict E.164 — leading + is required (e.g., +15551234567 ). Without the + the request returns 400 "Phone number must start with country code." See callout below. receiver_player_id integer No Explicit account selection when multiple player accounts share the receiver's phone on the destination game. Send the player_id chosen from the needs_account_selection picker response. Only needed for disambiguation — see the picker response below. Phone format — strict E.164 receiver_player_phone is validated as strict E.164: a leading + followed by 10–15 digits. Common formatting ( (555) 123-4567 , spaces, dashes) is stripped server-side, but the + itself is required . Without it the backend returns: {"status": "error", "message": "Phone number must start with country code (e.g., +1234567890)"} The backend will not auto-prepend a default country code (e.g., assuming 5551234567 means +1 ) because the universal player identity hash and cross-tenant phone-binding security check require phones to canonicalize identically across tenants — guessing would silently misalign US and Canadian numbers with the same trailing digits. Your UI should canonicalize before submit. Either use a phone-input component that always emits E.164 ( react-phone-number-input , libphonenumber-js ), or normalize manually: function toE164(input, defaultCountry = 'US') { if (!input) return null; if (input.startsWith('+')) return input.replace(/[^\d+]/g, ''); const digits = input.replace(/\D/g, ''); if (defaultCountry === 'US' && digits.length === 10) return `+1${digits}`; if (defaultCountry === 'US' && digits.length === 11 && digits[0] === '1') return `+${digits}`; return null; // ambiguous — surface a 'include country code' hint } The same rule applies to every phone field on every transfer/send endpoint ( source_player_phone , target_player_phone , receiver_player_phone ) — fix it once at your input layer. Claim Code Requirements Code Format • Format: ABCDE-12345 (5 letters · hyphen · 5 digits, 11 chars total) • Uppercase letters only, excluding O (to avoid 0/O confusion) • Digits 1–9 only, excluding 0 (same reason) • Case-sensitive, unique per currency send, one-time use • Example: KJMRS-47281 Time Limits • Code expires in 24 hours • Maximum 5 claim attempts • Failed attempts count toward rate limits • Expired codes cannot be reused How to Get a Claim Code SMS Notification Process When someone sends you currency, you'll automatically receive an SMS notification with all the details you need to claim it: "You have received 450.00 Gold from PlayerOne. Claim code: KJMRS-47281. Use this in Space Warriors. Expires in 24 hours." • Amount & Currency: How much currency you're receiving • Sender Name: Who sent the currency to you • Claim Code: The code you'll enter to claim the currency • Target Game: Which game to claim the currency in • Expiration: 24-hour time limit to claim Implementation Examples Unity Unity C# Currency Claim // This function MUST be called on your secure server, NOT the client. public IEnumerator ClaimSentCurrency(string claimCode, string receiverName, string receiverEmail, string receiverPhone, Action<string> onSuccess, Action<string> onError) { string url = "https://invo.network/api/currency-sends/claim-currency"; var requestData = new { claim_code = claimCode, receiver_player_name = receiverName, receiver_player_email = receiverEmail, receiver_player_phone = receiverPhone }; string jsonBody = JsonUtility.ToJson(requestData); using (UnityWebRequest request = new UnityWebRequest(url, "POST")) { byte[] bodyRaw = System.Text.Encoding.UTF8.GetBytes(jsonBody); request.uploadHandler = new UploadHandlerRaw(bodyRaw); request.downloadHandler = new DownloadHandlerBuffer(); request.SetRequestHeader("X-Game-Secret-Key", "receiving_game_secret_key_here"); request.SetRequestHeader("Content-Type", "application/json"); yield return request.SendWebRequest(); if (request.result == UnityWebRequest.Result.Success) { onSuccess?.Invoke(request.downloadHandler.text); } else { onError?.Invoke(request.error + ": " + request.downloadHandler.text); } } } Unreal Unreal C++ Currency Claim // This function MUST be called on your secure server. void AYourGameMode::ClaimSentCurrency(const FString& ClaimCode, const FString& ReceiverName, const FString& ReceiverEmail, const FString& ReceiverPhone) { TSharedPtr<FJsonObject> RequestObj = MakeShareable(new FJsonObject); RequestObj->SetStringField("claim_code", ClaimCode); RequestObj->SetStringField("receiver_player_name", ReceiverName); RequestObj->SetStringField("receiver_player_email", ReceiverEmail); RequestObj->SetStringField("receiver_player_phone", ReceiverPhone); FString RequestBody; TSharedRef<TJsonWriter<>> Writer = TJsonWriterFactory<>::Create(&RequestBody); FJsonSerializer::Serialize(RequestObj.ToSharedRef(), Writer); TSharedRef<IHttpRequest> Request = FHttpModule::Get().CreateRequest(); Request->SetURL("https://invo.network/api/currency-sends/claim-currency"); Request->SetVerb("POST"); Request->SetHeader("X-Game-Secret-Key", "receiving_game_secret_key_here"); Request->SetHeader("Content-Type", "application/json"); Request->SetContentAsString(RequestBody); Request->OnProcessRequestComplete().BindUObject(this, &AYourGameMode::OnCurrencyClaimed); Request->ProcessRequest(); } Godot Godot GDScript Currency Claim # This function MUST be called on your secure server. func claim_sent_currency(claim_code: String, receiver_name: String, receiver_email: String, receiver_phone: String): var url = "https://invo.network/api/currency-sends/claim-currency" var headers = [ "X-Game-Secret-Key: receiving_game_secret_key_here", "Content-Type: application/json" ] var body = { "claim_code": claim_code, "receiver_player_name": receiver_name, "receiver_player_email": receiver_email, "receiver_player_phone": receiver_phone } http_request.request(url, headers, HTTPClient.METHOD_POST, JSON.stringify(body)) Request & Response Examples Example Request POST /api/currency-sends/claim-currency Content-Type: application/json X-Game-Secret-Key: receiving_game_secret_key_here { "claim_code": "KJMRS-47281", "receiver_player_name": "PlayerTwo", "receiver_player_email": "player2@example.com", "receiver_player_phone": "+1987654321" } Success Response (200 OK) { "status": "success", "message": "Currency send claimed successfully.", "transaction_id": "txn_send123abc456", "new_balance": "1450.00", "currency_name": "Gold", "send_details": { "amount_received": "450.00", "sending_game": "Adventure Quest", "receiving_currency": "Gold", "receiver_player": "PlayerTwo", "new_balance": "1450.00" }, "completion_time": "2024-06-24T15:30:00Z", "order_id": "ord_send789def012" } Top-level new_balance is the canonical post-write balance — the receiver's available balance in the receiving game after the credit. The same value is mirrored in send_details.new_balance for legacy callers; prefer the top-level field. currency_name is the receiving game's currency. Error Response - Phone-Share Approval Required (409 Conflict) { "status": "error", "error_code": "PHONE_SHARE_APPROVAL_REQUIRED", "message": "This phone number is already linked to another Invo account. The existing phone owner must approve via SMS before this email can also use this phone.", "phone": "+15551234567", "requesting_email": "bob@example.com", "existing_account_hints": ["al***@example.com"], "next_endpoint": "/api/wallet/phone-share/initiate", "approval_id": "1f2a8c0d-...", "expires_at": "2026-05-04T22:25:00+00:00", "code_sent": true, "already_approved": false } Fires when the receiver's email is new on a phone that's already on file with a different email. Same contract for game-developer SDK integrations and platform-tier partners. The OTP SMS is auto-sent — have the existing phone owner read the SMS, then call POST /api/wallet/phone-share/approve with the approval_id from the body and the 6-digit OTP, then retry the claim. Only call /phone-share/initiate manually if code_sent: false . Match on error_code , not message text . If already_approved: true : auto-retry the claim immediately, do not show the OTP entry UI. The flag means a concurrent approval landed between gate-check and response — the pair is approved on the backend; the gate fired in a brief race window. The retry will succeed. One retry, no loops. Anti-abuse fields (optional, present only when triggered): cooldown_seconds appears when a fresh OTP for the same (phone, email) was minted less than 30s ago — no new SMS is sent , the previous code on the user's phone is still valid, and the included approval_id is the same row. Show the OTP entry panel as normal; do not show "code not sent" copy and do not auto-call /phone-share/initiate until the cooldown elapses. rate_limited: true + retry_after_seconds appear when this phone has hit the platform-wide 40-OTP-per-hour cap — no SMS sent, no approval_id returned, surface "please wait before requesting another code." Two equally valid approval paths the user can choose between: (1) type the 6-digit code into your UI → call POST /api/wallet/phone-share/approve , or (2) text the code back from their phone (Invo's inbound webhook approves server-side). If a user takes path 2, your client gets no direct callback — poll GET /api/wallet/phone-share/status?phone=...&email=... every 3–5s while your panel is open and auto-retry the claim when approved: true . Account Selection — Multi-Email-on-Phone (200 OK with picker shape) { "status": "needs_account_selection", "claim_code": "ABCDE-12345", "message": "Multiple accounts share this phone number on the destination game and the supplied email did not match any of them. Re-submit with receiver_player_id set to the chosen account, or fix the receiver_player_email.", "candidates": [ { "player_id": 12345, "email_hint": "al***@example.com" }, { "player_id": 67890, "email_hint": "bo***@example.com" } ] } Why this fires: Invo's wallet model supports multiple emails on one verified phone (parent + child, two-account gamers, family-shared device). When the destination game has 2+ Player rows on the same phone, the claim endpoint resolves which one to credit using this priority order: receiver_player_id in the request body (must match a candidate) — your client's explicit picker selection. receiver_player_email matches exactly one candidate's email — the common case. The user already typed their email into your claim form, so we don't prompt twice. No picker fires. Picker response (the 200 above) — only when steps 1 and 2 both fail. Recovery: render a picker from candidates showing each email_hint , let the user tap one, then re-submit /claim-currency with the same body PLUS receiver_player_id set to the chosen player_id . Status code is 200 not an error — the call hasn't failed, it just needs disambiguation. Most claims never see this response. It surfaces only in genuinely ambiguous cases (e.g., the user typo'd their email). Implementing the picker UI is a low-effort defensive measure — same shape applies to /claim-transfer . Error Response - Invalid Claim Code (400 Bad Request) { "status": "error", "message": "Invalid claim code.", "attempts_remaining": 4 } Error Response - Expired Code (400 Bad Request) { "status": "error", "message": "Claim code is not valid: Claim code expired." } Error Response - Send Not Found (404 Not Found) { "status": "error", "message": "Invalid claim code or currency send not intended for this game." } Error Response - Wrong Claim Endpoint (400 Bad Request) Returned when a claim code exists for this game but was minted by the cross-game self-transfer flow rather than the player-to-player send flow. Switch your call to /api/transfers/claim-transfer with target_* field names + target_currency_id . { "status": "error", "error_code": "WRONG_CLAIM_ENDPOINT", "message": "This claim code is for a self-transfer. Use POST /api/transfers/claim-transfer instead.", "expected_endpoint": "/api/transfers/claim-transfer", "expected_body_fields": [ "claim_code", "target_player_name", "target_player_email", "target_player_phone", "target_currency_id" ] } Switch on error_code === "WRONG_CLAIM_ENDPOINT" in your handler — message text may evolve, but the code and expected_endpoint field are stable contract. Error Response - Phone Number Mismatch (403 Forbidden) { "status": "error", "message": "Phone number mismatch: This claim code can only be redeemed by the intended recipient's phone number." } Error Response - Claim Attempt Lockout (429 Too Many Requests) Shipped 2026-05-14. Every failed claim attempt — wrong code, wrong phone, wrong endpoint, wrong PIN — writes an audit row keyed on phone + email + IP. When any dimension trips its trailing-window threshold, the endpoint returns 429 with error_code: "CLAIM_LOCKED" . Match on the code, not message text. HTTP/1.1 429 Too Many Requests Retry-After: 1800 { "status": "error", "error_code": "CLAIM_LOCKED", "error": "invalid_claim_code_blocked", "message": "Too many failed claim attempts for this phone number. Please wait 30 minutes before trying again.", "locked_dimension": "phone", "retry_after_seconds": 1800, "retry_after": 1800 } Two equivalent ways to match: new integrations should switch on error_code === "CLAIM_LOCKED" . Existing integrations whose security-block handler keys on the legacy field can switch on error === "invalid_claim_code_blocked" — both fields are present on every lockout response. Same goes for the duration field: retry_after_seconds (canonical) and retry_after (legacy alias) carry the same value. Dimension Threshold Window Lockout receiver_player_phone 5 failures trailing 30 min 30 min receiver_player_email 5 failures trailing 30 min 30 min ip_address 20 failures trailing 60 min 60 min Read retry_after_seconds (also in the Retry-After header) to drive your back-off. locked_dimension is informational — your UI should treat all three the same way (don't leak which dimension tripped). locked_dimension: "db_unavailable" indicates a transient Invo-side issue with retry_after_seconds: 60 ; retry shortly. 🔒 BREAKING CHANGE: Phone-Based Security As of the latest update, claim codes can ONLY be redeemed by the exact phone number specified during send initiation via receiver_player_phone . • The receiver_player_phone provided during claim MUST exactly match the receiver_player_phone from initiation • Phone mismatch results in 403 Forbidden error • This prevents unauthorized claim code sharing and redemption • Enhances security for player-to-player currency sends What Happens During a Successful Claim Currency Credited The net send amount (original amount minus fees) is immediately credited to the receiver's balance in the receiving game. If the player doesn't exist in the receiving game, a new player account is automatically created. Send Completed The send status is updated to "completed" and the transaction is finalized. The sender's reserved funds are permanently deducted, and fee distributions are recorded for all participating games and the platform. SMS Confirmation A confirmation SMS is sent to the receiver's phone number confirming the successful claim: "Invo Currency Claimed: You have successfully claimed 450.00 Gold from a currency send via Adventure Quest." Implementation Best Practices User Experience • Provide clear claim code input validation and formatting hints • Display remaining attempts when claim fails • Show clear success messages with amount received • Update player balance immediately in UI after successful claim • Pre-populate player fields if user is logged in • Show sender information clearly (who sent the currency) Error Handling • Parse error responses to show user-friendly messages • Handle rate limiting gracefully with retry suggestions • Differentiate between expired codes and invalid codes • Log claim attempts for customer support purposes • Implement proper timeout handling for network requests Security • Never log or store claim codes in your application • Validate claim code format before API submission • Clear claim code input fields after processing • Use HTTPS for all API communications • Validate phone number format on client side Player Onboarding • Validate email format before submission • Ensure phone numbers include country codes • Provide helpful onboarding for new players claiming their first currency • Confirm player details before final claim submission • Explain what happens after successful claim • Guide new players through account creation process

---

## In-App Verification

URL: https://docs.invo.network/docs/in-app-verification

Verify cross-game transfers and player-to-player sends in-app with a hardware-backed device signature. Faster, SIM-swap resistant, and reduces SMS costs. Additive and opt-in per game; SMS stays as the fallback.

In-App Verification The modern way to verify cross-game transfers and player-to-player sends — the player approves right inside your app with a hardware-backed signature, instead of typing an SMS PIN. It is faster, dramatically reduces SMS costs, and resists SIM-swap attacks that a texted code cannot. Why in-app verification SIM-swap resistant Approval is a signature from a key sealed in the device's secure hardware — it can't be intercepted or forwarded like an SMS code. Fewer SMS, lower cost The in-app prompt replaces the per-step verification text. SMS stays only as a fallback for players who don't have the app. Seamless UX The player taps approve in your game — no leaving the app to read a text and type a code back. Additive and opt-in — nothing you have today breaks In-app verification is a new, parallel set of endpoints under /api/sdk/* . Your existing initiate → verify-sms → claim integration is unchanged and keeps working. It is enabled per game . Your game stays entirely on the SMS flow until Invo enables in-app verification for it (coordinated with you, after your plugin is live and tested). Players without the app continue to receive the SMS PIN as before. On the web instead of a mobile app? This flow assumes a mobile app with secure hardware. Web platforms get the same hardware-backed, phishing-resistant step-up using WebAuthn passkeys in the browser — an additive alternative to the device signature that lands on the exact same approval. See Platform Step-Up (WebAuthn / Passkeys) . How the flow works ENROLL (once, on login) Your server ──(X-Game-Secret-Key)──▶ POST /api/sdk/player-token ──▶ player token ──▶ device Device generates a hardware keypair ─▶ POST /api/sdk/device/register (sends the PUBLIC key only) PER TRANSFER / SEND Your server starts it as normal (initiate-transfer / initiate-send). The device polls GET /api/sdk/transfers/pending (the authoritative to-do list) The player taps approve; the device SIGNS the action and calls POST /api/sdk/transfers/{id}/approve (self-transfer) POST /api/sdk/send/{id}/approve (player-to-player send) For a SEND, the receiver confirms in their app: POST /api/sdk/send/{id}/confirm-receipt FALLBACK A player without the app uses the existing SMS PIN flow (verify-sms) exactly as today. A push is not required — the device polls GET /api/sdk/transfers/pending on open and while in the foreground to discover what needs approval. That endpoint is always the source of truth. Telling a user they have something to collect A common question: "when a transfer or send arrives, how do I notify the logged-in user there's something to collect?" The pattern is pull for truth, push for wake-up : In-app: poll the pending list On app open, on foreground, and on a light interval while active (e.g. every 20–30s), call GET /api/sdk/transfers/pending with the player token and render its items: • receiving_confirm → "You have X to collect" from a peer send → route to confirm-receipt. • identity_gate → "Approve your transfer/send" (your own initiated action). Safe to drive UI directly — no raw PII (counterparty is a tenant name ; amounts + currency only). Closed app: webhook → your own push To notify when the app isn't open, your backend subscribes to our webhooks ( transfer.claim_pending and the inbound send event) and fires your own push (FCM / APNs / web-push). We deliver server-to-server webhooks; we don't push to devices. The push is a wake-up only — the app must still call /pending for the authoritative list (payloads can be delayed, duplicated, or arrive out of order). Recommendation: poll-on-open covers the in-app case with zero extra infrastructure; add the webhook→push path only when you need to alert users whose app is backgrounded or closed. Never treat a push payload as the source of truth — re-fetch /pending . See Receiving Webhooks for the event contract. The auth model (read this first) Never put your game secret on the device The X-Game-Secret-Key is server-side only . The device authenticates as the player , using a short-lived player token your server mints for it. A secret on the client is a leaked secret. Credential Lives where Authenticates Used for X-Game-Secret-Key Your server only The game Minting player tokens; your existing server APIs player token The player's device The player Every /api/sdk/* call from the device (as Authorization: Bearer ) The player token is short-lived (15 minutes) and there is no refresh call. On a 401 , mint a fresh one via your server's /api/sdk/player-token call and retry — never re-prompt the player just to refresh. The endpoints POST /api/sdk/player-token Server mints a short-lived player token (X-Game-Secret-Key) Device Enrollment POST /api/sdk/device/register Register the device + its hardware public key Device Enrollment GET /api/sdk/transfers/pending The authoritative list of actions awaiting this player Approve in App POST /api/sdk/transfers/{id}/approve Approve a self-transfer with a device signature Approve in App POST /api/sdk/send/{id}/approve Approve a player-to-player send (sender side) Approve in App POST /api/sdk/send/{id}/confirm-receipt Receiver confirms an incoming send Confirm Receipt GET /api/transfers/{id}/status Server-side: detect one transfer’s verification completion (X-Game-Secret-Key) Approve in App GET /api/currency-sends/{id}/status Server-side: detect one send’s verification completion (X-Game-Secret-Key) Approve in App Getting started Integrate the Invo plugin / SDK in your client (Unity / Unreal / native). On login, have your server mint a player token and the device register itself ( Device Enrollment ). Poll /api/sdk/transfers/pending and render the approve / confirm prompts ( Approve in App , Confirm Receipt ). Test in sandbox. When you're ready, Invo enables in-app verification for your game — players migrate as they update; SMS stays as the fallback.

---

## Device Enrollment

URL: https://docs.invo.network/docs/device-enrollment
Endpoint: POST /api/sdk/device/register

Mint a short-lived player token server-side and register a device with its hardware-backed public key. The signing contract (device_signal) and key rotation for in-app verification.

Device Enrollment Two one-time steps on login: your server mints a short-lived player token for the device, and the device registers itself plus a hardware-backed public key . That key is what every approval signature is verified against. 1. Mint a player token (server-side) POST /api/sdk/player-token Mints a short-lived token for one of your players Server-side only This is the one SDK call that uses your game secret. Call it from your server , then hand the returned token to the device. Never ship the secret to the client. X-Game-Secret-Key: your_game_secret_key_here Request Body Parameter Type Required Description player_email string Yes An existing player in your game Response { "token": "<player token — hand this to the device>", "expires_at": "2026-01-01T12:15:00Z", // 15-minute lifetime "identity_id": "id_9f3c…" // opaque player identity (safe to store) } The raw internal identity is never returned — only the opaque identity_id . A player not found in your game returns 404 player_not_found ; a game not yet enabled for in-app verification returns 403 sdk_not_enabled_for_tenant . 2. Register the device (client-side) POST /api/sdk/device/register Registers the device + its hardware public key under the player's identity Authenticated with the player token Authorization: Bearer <player token> Generate the keypair in secure hardware At registration the plugin generates a keypair inside the device's secure hardware (iOS Secure Enclave / Android StrongBox) and sends only the public key. The private key never leaves the device and is never transmitted or logged. Request Body Parameter Type Required Description device_fingerprint string Yes A stable per-device identifier (≤128 chars) device_public_key string Recommended PEM or base64-DER public key from the hardware keystore key_algorithm string With key EC_P256 | ED25519 | RSA_2048 platform string No ios | android | web | other rotation_proof object Only to rotate Required to change an existing key — see "Rotating a key" below Response { "status": "registered", "device": { "identity_id": "id_9f3c…", "platform": "ios", "has_attestation_key": true, "key_algorithm": "EC_P256" } } The device object is a partial view — the four fields above aren't exhaustive. It also includes id , is_active , last_seen_at , and created_at . The approval signature ( device_signal ) Every approval and receipt confirmation carries a device_signal — a signature over the exact action, made with the device's hardware private key. Sign exactly this canonical message: message = "{action}|{transfer_id}|{nonce}|{timestamp}" // UTF-8 bytes, pipe-delimited // action = the endpoint verb: "approve" when calling /approve, // "confirm-receipt" when calling /confirm-receipt. device_signal = { "transfer_id": "<the transaction id being approved>", "nonce": "<fresh random, single-use, base64url, no '|'>", "timestamp": 1750000000, // epoch SECONDS, must be within ±300s of server time "signature": "<base64 signature over message>" } • Action verb (required): the message is prefixed with the endpoint verb — approve or confirm-receipt — so a signature minted for one endpoint can't be reused at the other. Sign with the verb for the endpoint you're calling. • Algorithms: EC_P256 (ECDSA / SHA-256), ED25519 (raw message), RSA_2048 (PKCS#1 v1.5 / SHA-256) — must match the registered key. • The nonce is single-use ; do not reuse it on a retry — generate a fresh signal. • Because the private key never leaves the device, a signal can't be lifted onto another device, and the nonce + timestamp stop replay on the same device. Rotating a key Changing an enrolled key needs proof of the old one The first key for a player enrolls freely. Replacing or adding a different key for a player who already has one requires a rotation_proof — a signature made with the current private key over the new key. • A missing proof returns 409 rotation_requires_proof . • An invalid / stale / replayed / malformed proof returns 409 with the specific code ROTATION_PROOF_INVALID | ROTATION_PROOF_STALE | ROTATION_PROOF_REPLAY | ROTATION_PROOF_MALFORMED . message = "key-rotation|{new_public_key}|{nonce}|{timestamp}" // signed with the EXISTING key "rotation_proof": { "nonce": "…", "timestamp": 1750000000, "signature": "<base64>" } Example — register on login (Unity) // 1) Your SERVER mints the token (X-Game-Secret-Key) and returns it to the client. // 2) On the device, the plugin generates the hardware keypair and registers: IEnumerator RegisterDevice(string playerToken, string deviceFingerprint, string publicKeyPem) { var body = JsonUtility.ToJson(new { device_fingerprint = deviceFingerprint, device_public_key = publicKeyPem, key_algorithm = "EC_P256", platform = "ios" }); using (var req = new UnityWebRequest("https://invo.network/api/sdk/device/register", "POST")) { req.uploadHandler = new UploadHandlerRaw(System.Text.Encoding.UTF8.GetBytes(body)); req.downloadHandler = new DownloadHandlerBuffer(); req.SetRequestHeader("Authorization", "Bearer " + playerToken); req.SetRequestHeader("Content-Type", "application/json"); yield return req.SendWebRequest(); // on 401 → mint a fresh token via your server, then retry. } }

---

## Approve in App

URL: https://docs.invo.network/docs/app-approve
Endpoint: POST /api/sdk/transfers/{id}/approve

Poll the pending list and approve a transfer or send with a hardware device signature instead of an SMS PIN, including biometric step-up handling.

Approve in App The sender approves a transfer or send from inside your app. The device polls the pending list, renders the prompt, and posts a hardware signature instead of an SMS PIN. 1. Poll the pending list GET /api/sdk/transfers/pending The authoritative list of actions awaiting this player Poll this — there is no push to wire up Call it on app open / login and periodically while foregrounded. Always render prompts from this response (amount, currency, whether a step-up is needed) — never from anything cached. Authorization: Bearer <player token> Response { "pending": [ { "transfer_id": "TX_abc123", "kind": "identity_gate", // sender must approve "flow": "transfer", // "transfer" → /transfers/{id}/approve "amount": "100.00", // "send" → /send/{id}/approve "currency": "GoldCoins", "counterparty_game": "Game B", // destination "expires_at": "2026-01-01T18:05:00Z", // display only "step_up_required": false, // only present when risk step-up is enabled for your game; // if true, prompt biometric/PIN before approving "held": false, // true → not actionable yet (e.g. guardian pending) "hold_reason": null } ] } Items with kind: "receiving_confirm" are incoming sends to confirm — see Confirm Receipt . An item with held: true is awaiting something else (e.g. a guardian) — show it as pending, not approvable. Read this before you build the "you have X to collect" screen /pending is scoped to the logged-in player's token and returns exactly two kinds: • identity_gate — a transfer/send this player initiated , awaiting their approval (sender view). • receiving_confirm — a peer send addressed to this player (phone-matched), awaiting their collect (receiver view). Two traps: (1) the sender and receiver are different identities — a dev logged in as the sender will NOT see the receiver's collect item, and vice-versa; test each side with its own player token. (2) receiving_confirm is PEER-SENDS only. A self-transfer (same human, two of their own games) has no receiver item — the sender claims it at the destination with the claim code. So polling /pending as the "receiver" of a self-transfer correctly returns [] . To exercise the receiver collect flow, use a peer send . Detecting completion (poll /status ) GET /api/sdk/transfers/pending is for discovery — it's the player's to-do list, authed with the player token. To detect that a specific transfer's sender approval has completed (so you can dismiss a waiting panel), poll that one transfer's /status instead. GET /api/transfers/ {id} /status Status of one self-transfer GET /api/currency-sends/ {id} /status Status of one player-to-player send These are server-side endpoints — NOT the SDK player token Unlike the /api/sdk/* calls, both /status endpoints are authed with your X-Game-Secret-Key from your server — never the device player token. Poll them server-side. They return a verification_state that flips awaiting → approved the moment the sender clears the gate — whether in-app or via SMS: verification_state Meaning awaiting Sender hasn't cleared the gate yet — keep the waiting panel up approved Sender cleared the gate (in-app or SMS) — dismiss the waiting panel completed Fully resolved (claimed / credited) expired Window lapsed — stop polling failed Did not succeed — stop polling Use /status for a waiting panel keyed to one transfer; use /pending for discovery of what's awaiting the player. 2. Approve with a device signature Pick the endpoint by the item's flow . The body is identical for both. POST /api/sdk/transfers/ {id} /approve Self-transfer (your own balance between your games) POST /api/sdk/send/ {id} /approve Player-to-player send (sender side) Authenticated with the player token Authorization: Bearer <player token> Request Body Parameter Type Required Description device_fingerprint string Yes Which enrolled device is approving device_signal object Yes Signature over the action — see Device Enrollment biometric_verified boolean If stepped up Honest result of the biometric / PIN step-up, when required Success Response { "status": "approved", "next": "pending_claim", "transaction_id": "TX_abc123" } Other responses to handle Status Meaning / what to do 202 STEP_UP_REQUIRED May be returned when risk step-up is enabled for your game — prompt biometric / PIN, then retry with biometric_verified: true . A no-op when the flag is off. 202 RISK_HOLD May be returned when risk step-up is enabled for your game — held for review; do not retry, show a pending state. A no-op when the flag is off. 202 pending_guardian_approval Awaiting the guardian (minor) — show pending 410 GUARDIAN_APPROVAL_REJECTED Guardian rejected the action — stop; do not retry 410 GUARDIAN_APPROVAL_EXPIRED Guardian approval window lapsed — stop; do not retry 503 GUARDIAN_APPROVAL_CHECK_UNAVAILABLE Transient — the guardian check is temporarily unavailable; retry shortly 503 sdk_verification_disabled In-app verification is off for this game — fall back to the SMS flow 401 SIGNAL_* Bad/stale/replayed signature — re-sign with a fresh device_signal 400 (not pending) Already resolved — treat as "already done" After approval A self-transfer moves to pending_claim and you claim it as usual. A send moves to pending_claim and the receiver is notified to confirm ( Confirm Receipt ). The downstream claim flow is unchanged. Example — approve a transfer (Unity) IEnumerator ApproveTransfer(string playerToken, string transferId, string deviceFingerprint, object deviceSignal) { var url = "https://invo.network/api/sdk/transfers/" + transferId + "/approve"; var body = JsonConvert.SerializeObject(new { device_fingerprint = deviceFingerprint, device_signal = deviceSignal, // { transfer_id, nonce, timestamp, signature } biometric_verified = true }); using (var req = new UnityWebRequest(url, "POST")) { req.uploadHandler = new UploadHandlerRaw(System.Text.Encoding.UTF8.GetBytes(body)); req.downloadHandler = new DownloadHandlerBuffer(); req.SetRequestHeader("Authorization", "Bearer " + playerToken); req.SetRequestHeader("Content-Type", "application/json"); yield return req.SendWebRequest(); // 202 STEP_UP_REQUIRED → run biometric, re-sign, retry. } } Report biometric_verified honestly . If the step-up fails or the user cancels, send false — Invo decides what happens. Never complete an action locally.

---

## Confirm Receipt

URL: https://docs.invo.network/docs/app-confirm-receipt
Endpoint: POST /api/sdk/send/{id}/confirm-receipt

The receiver confirms an incoming player-to-player send in-app with a device signature; the funds are credited and the send completes. Claim-code remains the fallback.

Confirm Receipt The in-app way to claim incoming value with a device signature or passkey instead of typing a claim code. There are two flavours, with the same request/response shape: Send — the receiver (a different person) confirms an incoming player-to-player send. Transfer — the same person claims their own cross-game transfer into the destination game (a self-claim). This replaces the claim-code + SMS step for enrolled users. POST /api/sdk/send/ {id} /confirm-receipt Receiver confirms an incoming send; the funds are credited and the send completes Authenticated with the RECEIVER's player token The token is minted by the receiving game for the receiver. The receiver's enrolled phone must match the one the send was addressed to. Authorization: Bearer <receiver's player token> Request Body Parameter Type Required Description device_fingerprint string Yes Which enrolled device is confirming device_signal object Yes Signature over the action — see Device Enrollment biometric_verified boolean If stepped up Honest result of the step-up, when required Success Response { "status": "completed", "transaction_id": "TX_send789", "amount_received": "90.00" } POST /api/sdk/transfers/ {id} /confirm-receipt The same person claims their own cross-game transfer into the destination game — no claim code, no SMS Authenticated with the claimer's player token in the DESTINATION game A cross-game transfer is a self-claim: the same identity that sent it claims it on the other side. Use the player token minted by the destination game; the enrolled phone must match the one the transfer was addressed to. Authorization: Bearer <claimer's destination-game player token> Same request body and success shape as the send endpoint above ( device_fingerprint + device_signal , or a webauthn_assertion for passkey platforms; optional biometric_verified ). On success the destination balance is credited and the transfer completes. { "status": "completed", "transaction_id": "TX_transfer456", "amount_received": "100.00" } Passkey challenge (WebAuthn platforms) For a passkey assertion, first get a challenge from POST /api/sdk/transfers/ {id} /confirm-receipt/webauthn/begin , complete it, then send the result as webauthn_assertion . The device-signature path needs no begin call. How the app discovers something to confirm SENDS (someone sent to your player): the app polls GET /api/sdk/transfers/pending ; an incoming send appears as an item with kind: "receiving_confirm" (amount, source game, expiry). Render the prompt, then call /api/sdk/send/ {id} /confirm-receipt . ⚠️ TRANSFERS are NOT in /sdk/transfers/pending 's receiver list — that list is peer-sends only. A transfer is a self-claim, so discover it one of two ways: (1) your backend subscribes to the transfer.claim_pending webhook and/or polls the server-side GET /api/transfers/inbound-pending?player_email=… list (game-secret authed) to enumerate inbound transfers for a player; or (2) the sender's app already holds the claim_code returned in-band from /api/sdk/transfers/ {id} /approve . Then call /api/sdk/transfers/ {id} /confirm-receipt to collect. Other responses to handle Status Meaning / what to do 403 not_intended_receiver This player/phone isn't the addressed recipient 404 receiving_tenant_unavailable The receiving game can't be resolved right now — retry shortly 409 receiver_not_enrolled_use_claim_code No account in the receiving game yet — fall back to the claim-code flow 400 no_registered_device_key This receiver has no enrolled device key — register the device first (Device Enrollment) 202 STEP_UP_REQUIRED May be returned when risk step-up is enabled for your game — run biometric / PIN, then retry with biometric_verified: true . A no-op when the flag is off. 503 sdk_verification_disabled In-app verification is off for this game — fall back to the claim-code flow 401 SIGNAL_* Bad/stale/replayed signature — re-sign with a fresh device_signal 400 (cannot be confirmed) Already resolved — treat as "already done" Users without the app are unaffected Anyone not enrolled (no account/app in the destination game) simply uses the existing claim-code flow — the send or transfer still completes. For transfers, the claim code is also returned in-band from /transfers/ {id} /approve , so the app never needs to read it from an SMS. In-app confirm is the upgrade for enrolled users, not a requirement for everyone. If the endpoint returns 503 for your game, in-app confirm isn't enabled yet — fall back to the claim code.

---

## Platform Step-Up (WebAuthn / Passkeys)

URL: https://docs.invo.network/docs/platform-step-up

Add WebAuthn / passkey step-up to web platforms: phishing-resistant, hardware-bound, user-verified approval for high-value transfers and sends, hosted on your own origin. An additive alternative to the mobile device signature.

Platform Step-Up (WebAuthn / Passkeys) The in-app device flow assumes a mobile app with secure hardware. Web platforms don't have that — the user is in a browser. WebAuthn / passkeys give the same property on the web: a phishing-resistant, hardware-bound credential with user verification (Touch ID / Windows Hello / a security key) backing each high-value action. It's an additive alternative to the mobile device_signal — both land on the exact same approval. How it works You host the ceremony on your own domain The passkey is created and used on your web origin — the user never leaves your site. You register the resulting public credential with INVO and we verify every assertion against your configured relying-party ID and allowed origins. The private key stays on the user's device and is never transmitted. There are two ceremonies, mirroring the mobile flow: • Enrollment (once per browser/device) — create a passkey and register its public key. • Approval (per high-value action) — sign a challenge bound to the specific transfer or send. Two separate switches — verifying your domain does not enrol anyone These are the two most common points of confusion, so to be explicit: Verifying your domain turns passkeys on for the tenant . Once, by you. Enrolling a passkey happens per player , on their device, and you trigger it. A freshly verified tenant has zero enrolled players. Asking for approval before a player has enrolled returns 400 WEBAUTHN_NO_CREDENTIAL — that is expected, not a fault, and the action automatically falls back to SMS / in-app approval . Nothing is blocked and no money movement is lost. Run the enrolment ceremony below for a player before expecting a Face ID / Windows Hello prompt. Prerequisite — relying-party config (self-serve) Your domain must be verified first WebAuthn is offered to a platform only once its relying-party ID (your registrable domain, e.g. accounts.example.com ) and allowed web origins are configured for your tenant. Until then every endpoint below returns 403 WEBAUTHN_NOT_ENABLED_FOR_TENANT . Because an RP ID is a security-critical binding, you must prove you control the domain before the config goes live — it's a self-serve setup on the dashboard's Platform & Keys page, and you can prove control either by DNS record or by serving a file . Configure it on the Platform & Keys page 1 Submit your domain Sign in to the developer dashboard ( console.invo.network , or dev.console.invo.network for sandbox), open the user menu (top-right) → Platform & Keys → pick your game → Passkey step-up . Enter your RP ID — a bare registrable domain, no https:// , path, or port — and your allowed origins , one per line. Each origin must be an https:// origin on the RP ID or one of its subdomains (e.g. RP ID athero.com allows https://accounts.athero.com ). 2 Prove you control the domain — pick either method On submit, the console issues a one-off token and shows both options. Satisfy either one — they carry the same token and are equally valid. Option A — DNS TXT record Add this at your DNS provider: Host: _invo-webauthn.<your-rp-id> e.g. _invo-webauthn.accounts.athero.com Type: TXT Value: invo-verify=<token from the console> Option B — file on your site Serve the token as plain text at this exact path, over https : URL: https://<your-rp-id>/.well-known/invo-webauthn-challenge.txt Contents: invo-verify=<token from the console> The file must be served by the RP ID host itself. We follow no redirects and read plain text only — a redirect, a non-200, or an HTML page is treated as unverified. 3 Verify Back in the console, click Verify domain . We do a live TXT lookup; on a match the config is promoted to live and the endpoints below light up for your tenant immediately. If the record isn't visible yet, the console shows the exact host and value it looked for — DNS propagation can take a few minutes, so try again shortly. While a submission is pending, any existing live config keeps working unchanged; you can also change the domain or turn step-up off from the same card at any time. Hosted on *.web.app, *.netlify.app, *.vercel.app or *.pages.dev? Use Option B On a platform-provided hostname you have a hostname inside your host's DNS zone, not a zone of your own — so there is no DNS provider where you could add _invo-webauthn.<your-subdomain> . Option A can never succeed there; it isn't a propagation delay. Use the file method instead. Two things that silently break the file on static hosts: SPA rewrites. A catch-all rewrite ( "source": "**" → /index.html ) answers the challenge URL with your app's HTML and a 200 . That reads as unverified. Add an explicit rule so /.well-known/* is served as a real file, ahead of the catch-all. Dotfiles excluded from deploys. Firebase Hosting's default "ignore": ["**/.*"] in firebase.json drops the whole .well-known directory before upload, so the file 404s even though it exists locally. Remove or narrow that pattern. Verify with curl https://<your-rp-id>/.well-known/invo-webauthn-challenge.txt — you should see the token as plain text, not HTML. Choose the domain you intend to keep Passkeys are bound to the RP ID permanently — a credential enrolled under one RP ID cannot be moved to another. If you expect to move from a platform-provided hostname to your own domain later, set your own domain as the RP ID now and point the origins at it; otherwise every player has to re-enrol after the move. The same RP ID also backs native iOS/Android builds via associated domains, so it needs to be a domain you can serve .well-known files from long-term. 1. Enroll a passkey POST /api/sdk/webauthn/register/begin Returns PublicKeyCredentialCreationOptions for the browser Authenticated with the player token Authorization: Bearer <player token> Every WebAuthn call uses a short-lived player token , minted server-side (your game secret never touches the browser). Mint it with: POST /api/sdk/player-token Header: X-Game-Secret-Key: <your game secret> // server-to-server ONLY Body: { "player_email": "user@example.com" } → { "token": "<player token>", // use as Authorization: Bearer "expires_at": "2026-01-01T12:15:00Z", // ~15-minute lifetime, no refresh "identity_id": "id_9f3c…" } // 404 player_not_found · 403 sdk_not_enabled_for_tenant · on 401 mint a fresh token Full contract + key rotation: Device Enrollment . Pass the returned options straight to navigator.credentials.create() . The challenge is single-use and short-lived. POST /api/sdk/webauthn/register/complete Verifies the attestation and stores the credential Request Body Parameter Type Required Description credential object Yes The serialized result of navigator.credentials.create() (base64url-encoded fields) One passkey per identity (anti-takeover) The first passkey for a player enrolls freely; re-registering the same passkey is idempotent. Enrolling a different new passkey while one already exists is blocked with 409 ENROLLMENT_REQUIRES_PROOF — the same takeover protection as mobile key rotation. (Adding more passkeys is handled out-of-band today.) Client (browser) // options came from /register/begin. Convert base64url fields to ArrayBuffers // (challenge, user.id) before calling create(), then base64url-encode the // result's ArrayBuffers (rawId, attestationObject, clientDataJSON) to send back. const options = await (await fetch('/api/sdk/webauthn/register/begin', { method: 'POST', headers: { Authorization: 'Bearer ' + playerToken } })).json(); const cred = await navigator.credentials.create({ publicKey: toBuffers(options) }); await fetch('/api/sdk/webauthn/register/complete', { method: 'POST', headers: { Authorization: 'Bearer ' + playerToken, 'Content-Type': 'application/json' }, body: JSON.stringify({ credential: toJSON(cred) }) // base64url-encoded }); toBuffers / toJSON are the standard WebAuthn base64url ⇄ ArrayBuffer converters (libraries like @simplewebauthn/browser do this for you with startRegistration ). 2. Approve an action with the passkey Replace the SMS PIN (or the mobile device_signal ) with a passkey assertion. First get a challenge bound to the specific transaction , then submit the assertion to the same approval endpoint you'd use otherwise. POST /api/sdk/transfers/{id}/approve/webauthn/begin Returns PublicKeyCredentialRequestOptions bound to this transfer Companion begin endpoints exist for the send flow: /api/sdk/send/{id}/approve/webauthn/begin and /api/sdk/send/{id}/confirm-receipt/webauthn/begin . POST /api/sdk/transfers/{id}/approve Submit a webauthn_assertion instead of a device_signal Request Body Parameter Type Required Description webauthn_assertion object Yes The serialized result of navigator.credentials.get() Client (browser) const options = await (await fetch(`/api/sdk/transfers/${id}/approve/webauthn/begin`, { method: 'POST', headers: { Authorization: 'Bearer ' + playerToken } })).json(); const assertion = await navigator.credentials.get({ publicKey: toBuffers(options) }); const res = await fetch(`/api/sdk/transfers/${id}/approve`, { method: 'POST', headers: { Authorization: 'Bearer ' + playerToken, 'Content-Type': 'application/json' }, body: JSON.stringify({ webauthn_assertion: toJSON(assertion) }) }); // 200 { status: "approved", next: "pending_claim", claim_code: "…" } On success the action moves to exactly the same state as the SMS / mobile path — the rest of the lifecycle (claim, completion, webhooks) is unchanged. A failed or unverifiable assertion returns 401 ; an expired/missing challenge requires a fresh /begin . Handling /begin errors 400 WEBAUTHN_NO_CREDENTIAL — this player has no passkey yet. Not a failure. The action falls back to SMS / in-app approval on its own. Offer enrolment and carry on; don't surface it as an error. The response carries reason , enrollment (the two endpoints to call) and fallback . 403 WEBAUTHN_NOT_ENABLED_FOR_TENANT — no verified domain on the tenant. Check reason : no_verified_domain is self-serve (see above); unavailable_on_this_environment means contact INVO. 400 WEBAUTHN_BEGIN_FAILED — an unexpected server-side fault. This one is worth surfacing and reporting. Read code and message from the JSON body rather than treating any non-2xx as a network problem — the body always says which of the above it is. Why it's strong User verification required Every assertion requires a biometric or device PIN — it's a true step-up, not a silent token. Bound to the action The challenge is tied to the specific transaction, single-use — an assertion for one action can't approve another. Phishing-resistant The credential is bound to your origin; it can't be used from a look-alike site. Hardware-bound + clone detection The private key never leaves the authenticator, and a signature counter detects cloned credentials. Related: mint the player token server-side · approve/confirm contracts in Approve in App and Confirm Receipt · verify our outbound webhooks (X-Invo-Signature, HMAC-SHA256).

---

## Guardian Approval (Minor Accounts)

URL: https://docs.invo.network/docs/guardian-approval

Standard integration pattern for handling pending_guardian_approval (HTTP 202) on transfer and currency-send calls. Polling endpoint, state machine, suggested partner UI, and sandbox testing instructions.

Guardian Approval The Invo Network supports accounts flagged as belonging to a minor with a designated guardian. When a minor initiates a cross-game transfer or player-to-player send, the transaction is held until the guardian replies YES or NO to an SMS — within 15 minutes. This is the standard integration pattern going forward — implement it once and it covers all your users, including the majority who will never trigger the path. Implement defensively — you can't detect minor status from your side The minor flag lives on Invo's backend and is never exposed in API responses. There's no way for your client to look up "is this user a minor?" before initiating a transfer — and that's by design (privacy + compliance). Your integration should treat pending_guardian_approval as a normal possible response on every /initiate-* and /verify-sms call. For adult accounts (the vast majority of your traffic), the 202 path simply never fires — the response shape, status codes, and timing are identical to what you have today. Implementing the handler costs you ~50 lines of UI code and a polling loop. Once it's in, you're done forever — Invo can flag any account as a minor at any time and your integration handles it without redeploy. If you skip it: minor users on your platform see generic failures when they try to transfer/send. Adult users still work fine. Recommended: implement the 202 path as part of your standard integration checklist. Context: this is part of the wallet rollout Behind the scenes, Invo groups one human's emails (across tenants) under a single wallet keyed off their verified phone. This applies to all users , not just minors — many adults legitimately operate multiple emails on one phone (separate gaming accounts, pseudonymous handles, family-shared devices). The wallet model is what lets us: Skip redundant phone-share OTPs once an email is verified for a phone (better UX for everyone) Apply per-human guardrails like guardian approval (relevant when an account is flagged as a minor) Keep identity_id stable across a user's emails network-wide Your integration doesn't need to be aware of the wallet model directly — identity_id behaves the same as before, no new fields surface in API responses, and existing flows continue working. The 202 guardian-approval path documented here is the only partner-visible artifact of the wallet rollout, and it's the integration pattern we recommend for all new partners. What is and isn't gated Gated for minor accounts • /api/transfers/initiate-transfer • /api/transfers/verify-sms • /api/currency-sends/initiate-send • /api/currency-sends/verify-sms Not gated (intentionally) • Item purchases — currency was already approved when it entered the wallet • Currency top-ups — gated upstream at the parent's payment-method level • Claims — receiving currency, not sending it The guardrail is on value movement off the account . Spending balance on items is treated as already authorized at deposit time. Initiate response when guardian approval is needed When a minor initiates a transfer or send, the standard /initiate-transfer or /initiate-send endpoint returns HTTP 202 Accepted instead of 200/201 . The body includes all the standard fields plus a guardian_approval block: { "status": "pending_guardian_approval", "message": "Transfer initiated. SMS PIN sent to your phone, but verification is held until the guardian on file approves via SMS.", "transaction_id": "TXN_1715000000_ABC123", "guardian_approval": { "approval_id": "1f2a8c0d-...", "state": "pending", "expires_at": "2026-05-04T22:15:00+00:00", "poll_endpoint": "/api/transactions/TXN_1715000000_ABC123/approval-status" }, "transfer_details": { /* ...standard fields... */ }, "verification_required": { /* ...standard fields... */ } } The user's SMS PIN is still sent at initiate time. Show your normal PIN-entry UI, but disable the submit button and surface a "Waiting for parent approval" indicator until the polling endpoint says approved. Poll the approval status GET /api/transactions/<transaction_id>/approval-status Returns the current state of a transaction's guardian approval Authentication: X-Game-Secret-Key header (same as other partner endpoints). Recommended polling interval: 5–10 seconds . Response while pending { "status": "ok", "approval": { "approval_id": "1f2a8c0d-...", "transaction_id": "TXN_1715000000_ABC123", "state": "pending", "expires_at": "2026-05-04T22:15:00+00:00", "decided_at": null, "decision_source": null, "action_description": "send 50 IPC from GameX to GameY" } } Terminal states The state field transitions to one of: approved — guardian replied YES. The user can now submit their SMS PIN normally; the transfer will complete. rejected — guardian replied NO. Transaction is dead; show the user a clear message. expired — 15 minutes passed without a reply. Same as rejected from the user's perspective. When you see a terminal state, stop polling. decided_at tells you when the decision landed; decision_source is sms_inbound for guardian replies and expiry_job for time-outs. Transient 503 : the poll endpoint may return HTTP 503 { "status": "unavailable" } when the approval lookup is momentarily unavailable. This is not a terminal state — treat it as "keep polling / retry shortly" and try again on your next interval. Behavior on /verify-sms while pending If your user enters their SMS PIN and you call /verify-sms before the guardian has approved, the endpoint returns HTTP 202 with: { "status": "pending_guardian_approval", "error_code": "GUARDIAN_APPROVAL_PENDING", "message": "Verification is held until the guardian on file approves via SMS.", "guardian_approval": { /* current approval state */ } } The same call works once the approval lands — no extra step required from the user. They can leave the PIN entered, and as soon as the guardian replies, your client's next /verify-sms call (driven by your status polling) will succeed normally. Rejection / expiry If the guardian rejected or the window expired, /verify-sms returns HTTP 410 Gone : { "status": "error", "error_code": "GUARDIAN_APPROVAL_REJECTED", // or GUARDIAN_APPROVAL_EXPIRED "message": "The guardian on file rejected this transaction.", "guardian_approval": { /* state: "rejected" | "expired" */ } } Treat both as terminal — the transaction cannot be revived. Show the user a clear message and let them re-initiate if they want to try again (a fresh approval row will be created). Suggested partner UI flow 1 On 202 from initiate Show "Waiting for parent approval" with a countdown to expires_at . Keep the PIN-entry UI visible but disabled. SMS PIN is already on the user's phone. 2 Poll /approval-status every 5–10s Show subtle progress (e.g., "Still waiting..."). Stop polling at any terminal state. 3 On state === "approved" Enable the PIN-submit button. Optional message: "Parent approved — please enter your SMS PIN." The user proceeds with /verify-sms normally. 4 On state === "rejected" | "expired" Show the corresponding terminal message. Provide a "Try again" button that re-initiates a fresh transaction. Don't reuse the same client_request_id — generate a new one. What the guardian sees Inbound SMS to guardian's phone Invo Approval Request Alex wants to send 50 IPC from GameX to GameY. Reply YES ABC234XY56QZ to approve or NO ABC234XY56QZ to reject. Expires in 15 minutes. - Invo Platform The 12-character token in the SMS is single-use and embedded so a stray YES/NO can't match a stale request. The guardian must reply from the phone number on file ; replies from any other number are silently rejected by Invo's inbound webhook. Edge cases worth handling User refreshes the page mid-flow Cache the transaction_id client-side or in your backend. On reload, re-poll /approval-status to recover the state. Guardian replies but doesn't see your UI update The Invo backend transitions state on receipt of the SMS. Your polling will pick it up within 5–10s. If the user complains they pressed YES and nothing happened, ask them to wait a few seconds — the round-trip through Twilio and your polling cycle takes a moment. User submits PIN before approval lands Your /verify-sms call returns 202 GUARDIAN_APPROVAL_PENDING . Treat it the same as the polling response — keep showing "Waiting for parent." The PIN entry is preserved server-side; the next call after approval will succeed. "Our platform doesn't serve minors" You probably do, even if your TOS says otherwise — Invo's minor flag is set based on signals across the whole network, not your platform's self-reported audience. Implement the 202 path. If your audience really is 100% adult, the path is dead code; if you're wrong about your audience even occasionally, the dead code stops being dead and saves you a support escalation. Testing in sandbox Sandbox supports the same flow end-to-end. To test, contact your Invo onboarding rep to flag a test wallet as a minor with a guardian. Then: Initiate a transfer or send from the minor's player. Confirm you receive the 202 response. Watch the guardian's phone for the SMS. (Sandbox sends real SMS via Twilio.) Reply YES <token> from the guardian's phone. Continue polling — within ~5s, state should flip to approved . Submit the SMS PIN normally — the transfer completes. Repeat with NO <token> to verify your rejected-state UI. Don't reply for 15+ minutes to verify expiry. HTTP status code reference Status When What to do 202 Initiate succeeded but is awaiting guardian approval Show waiting UI, start polling 202 /verify-sms while approval still pending Keep waiting state, continue polling 200 /verify-sms after approval (or non-minor account) Normal success path 410 /verify-sms when guardian rejected or expired Show terminal message, offer re-init Implementation Examples The 202 detection + polling loop runs on your secure backend, alongside your existing /initiate-transfer code. The samples below show the full pattern in Unity C#, Unreal C++, Godot GDScript, and Node.js. Adapt to your language as needed — the contract is the same. Node.js Backend polling loop (works for any platform-tier integrator) // On your secure server. Call this AFTER /initiate-transfer or /initiate-send returns. // It returns the final approval state, or null if the response was 200/201 (no gate). async function handleInitiateResponse(initiateResponse, transactionId) { // 200/201 → no guardian needed. Proceed with normal verify flow. if (initiateResponse.status !== 202) return null; const body = await initiateResponse.json(); if (body.status !== 'pending_guardian_approval') return null; const expiresAt = new Date(body.guardian_approval.expires_at); const pollUrl = `https://invo.network${body.guardian_approval.poll_endpoint}`; while (Date.now() < expiresAt.getTime()) { await new Promise(r => setTimeout(r, 7000)); // 7s cadence (within 5-10s recommended) const statusRes = await fetch(pollUrl, { headers: { 'X-Game-Secret-Key': process.env.INVO_SDK_KEY }, }); const statusBody = await statusRes.json(); const state = statusBody.approval?.state; if (state === 'approved') return 'approved'; if (state === 'rejected') return 'rejected'; if (state === 'expired') return 'expired'; // state === 'pending' → keep polling } return 'expired'; // safety net } // Wiring it into your transfer flow: async function startTransfer(payload) { const initRes = await fetch('https://invo.network/api/transfers/initiate-transfer', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Game-Secret-Key': process.env.INVO_SDK_KEY, }, body: JSON.stringify(payload), }); const body = await initRes.json(); const transactionId = body.transaction_id; // Notify your client immediately so it can show "waiting for parent" UI. if (initRes.status === 202) { notifyClient(transactionId, { phase: 'pending_guardian', expires_at: body.guardian_approval.expires_at }); const finalState = await handleInitiateResponse(initRes, transactionId); if (finalState === 'rejected' || finalState === 'expired') { notifyClient(transactionId, { phase: 'guardian_terminal', state: finalState }); return; } notifyClient(transactionId, { phase: 'guardian_approved' }); } // Approved (or no gate) → proceed with the standard SMS PIN flow. // /verify-sms can now be called normally; it will succeed. } Unity Unity C# polling (server-side coroutine) // MUST run on your secure server, not the Unity client. // Call after InitiateTransfer returns and you've parsed the response. public IEnumerator PollGuardianApproval(string transactionId, DateTime expiresAt, Action<string> onApproved, Action<string> onTerminal /* "rejected" | "expired" */) { string url = $"https://invo.network/api/transactions/{transactionId}/approval-status"; while (DateTime.UtcNow < expiresAt) { yield return new WaitForSeconds(7f); // 7s cadence using (UnityWebRequest req = UnityWebRequest.Get(url)) { req.SetRequestHeader("X-Game-Secret-Key", "your_game_secret_key_here"); yield return req.SendWebRequest(); if (req.result != UnityWebRequest.Result.Success) continue; // network blip; keep polling // Parse: {"status":"ok","approval":{"state":"pending"|"approved"|"rejected"|"expired",...}} var body = JsonUtility.FromJson<ApprovalStatusResponse>(req.downloadHandler.text); string state = body.approval.state; if (state == "approved") { onApproved?.Invoke(transactionId); yield break; } if (state == "rejected" || state == "expired") { onTerminal?.Invoke(state); yield break; } // state == "pending" → keep polling } } onTerminal?.Invoke("expired"); // safety net } [Serializable] public class ApprovalStatusResponse { public string status; public ApprovalRow approval; } [Serializable] public class ApprovalRow { public string approval_id; public string transaction_id; public string state; public string expires_at; public string decided_at; public string decision_source; public string action_description; } Unreal Unreal C++ polling (server-side timer) // MUST run on your secure server. Schedule a recurring HTTP poll until // terminal state or expiry. void AYourGameMode::PollGuardianApproval(const FString& TransactionId, const FDateTime& ExpiresAt) { if (FDateTime::UtcNow() >= ExpiresAt) { OnGuardianTerminal(TransactionId, TEXT("expired")); return; } FString Url = FString::Printf( TEXT("https://invo.network/api/transactions/%s/approval-status"), *TransactionId); TSharedRef<IHttpRequest> Req = FHttpModule::Get().CreateRequest(); Req->SetURL(Url); Req->SetVerb("GET"); Req->SetHeader("X-Game-Secret-Key", "your_game_secret_key_here"); Req->OnProcessRequestComplete().BindLambda( [this, TransactionId, ExpiresAt](FHttpRequestPtr R, FHttpResponsePtr Resp, bool bOk) { if (!bOk || !Resp.IsValid()) { // network blip; reschedule GetWorld()->GetTimerManager().SetTimer(PollHandle, FTimerDelegate::CreateUObject(this, &AYourGameMode::PollGuardianApproval, TransactionId, ExpiresAt), 7.0f, false); return; } TSharedPtr<FJsonObject> Body; TSharedRef<TJsonReader<>> Reader = TJsonReaderFactory<>::Create(Resp->GetContentAsString()); FJsonSerializer::Deserialize(Reader, Body); FString State = Body->GetObjectField("approval")->GetStringField("state"); if (State == "approved") { OnGuardianApproved(TransactionId); return; } if (State == "rejected" || State == "expired") { OnGuardianTerminal(TransactionId, State); return; } // pending → reschedule another poll in 7s GetWorld()->GetTimerManager().SetTimer(PollHandle, FTimerDelegate::CreateUObject(this, &AYourGameMode::PollGuardianApproval, TransactionId, ExpiresAt), 7.0f, false); }); Req->ProcessRequest(); } Godot Godot GDScript polling (server-side) # MUST run on your secure server. # Returns "approved", "rejected", or "expired". func poll_guardian_approval(transaction_id: String, expires_at_iso: String) -> String: var expires_at_unix = Time.get_unix_time_from_datetime_string(expires_at_iso) var url = "https://invo.network/api/transactions/%s/approval-status" % transaction_id var headers = ["X-Game-Secret-Key: your_game_secret_key_here"] while Time.get_unix_time_from_system() < expires_at_unix: await get_tree().create_timer(7.0).timeout var req = HTTPRequest.new() add_child(req) var err = req.request(url, headers, HTTPClient.METHOD_GET) if err != OK: req.queue_free() continue var result = await req.request_completed var body_str = result[3].get_string_from_utf8() var body = JSON.parse_string(body_str) req.queue_free() var state = body.get("approval", {}).get("state", "") if state == "approved": return "approved" if state == "rejected" or state == "expired": return state # state == "pending" → keep polling return "expired" All Handling /verify-sms 202 / 410 responses // /verify-sms can return: // 200 → success, transfer proceeds // 202 + GUARDIAN_APPROVAL_PENDING → guardian still hasn't replied; same call works once approved // 410 + GUARDIAN_APPROVAL_REJECTED | GUARDIAN_APPROVAL_EXPIRED → terminal // 400/4xx → existing PIN errors (wrong code, expired PIN, etc.) — handle as today const verifyRes = await fetch('https://invo.network/api/transfers/verify-sms', { method: 'POST', headers: { 'Content-Type': 'application/json', 'X-Game-Secret-Key': SDK_KEY }, body: JSON.stringify({ transaction_id: txnId, sms_pin: pin }), }); if (verifyRes.status === 200) { // success — show claim instructions, etc. } else if (verifyRes.status === 202) { // guardian still pending — start polling /approval-status if not already } else if (verifyRes.status === 410) { const body = await verifyRes.json(); // body.error_code is GUARDIAN_APPROVAL_REJECTED or GUARDIAN_APPROVAL_EXPIRED // Show terminal message; user must re-initiate with a fresh client_request_id } else { // existing 400-class PIN errors } Implementation summary ✓ Detect 202 pending_guardian_approval on /initiate-* ✓ Poll GET /api/transactions/<id>/approval-status every 5–10s ✓ Handle the four states: pending , approved , rejected , expired ✓ On /verify-sms , treat 202 the same as polling-pending; treat 410 as terminal ✓ Test the flow in sandbox before relying on it in prod

---

## Wallet Identity Lookup

URL: https://docs.invo.network/docs/wallet-identity-lookup
Endpoint: GET /api/wallet/identities

GET /api/wallet/identities — fetch every email attached to a player’s Invo wallet so your UI can pre-populate the list. Game-secret authenticated, scoped to your game’s players only.

Wallet Identity Lookup Fetch every email attached to a player's Invo wallet so your UI can pre-populate the "your other accounts" list instead of asking the user to type each email manually. When to use this endpoint One human can legitimately operate multiple emails under one verified phone (parent + child, separate gaming handles, family-shared device). Once a phone is verified to a wallet, additional emails can be attached via the phone-share OTP flow. This endpoint returns the full email list for a player's wallet so your client can show the user "you also have x@y.com on this account" without making them remember. Typical UX: after a player logs in, call this endpoint with their email or phone to fetch the rest of their wallet's emails, then render them as switchable account chips in your UI. Endpoint GET /api/wallet/identities?player_email=<email> GET /api/wallet/identities?player_phone=<E.164 phone> Headers: X-Game-Secret-Key: <your_game_secret_key> Provide either player_email or player_phone (or both — they'll be AND-filtered). The player must already exist in your game; the endpoint does not return data for players in other games on the network. Authentication Game secret only. No JWT required. The endpoint requires X-Game-Secret-Key in the header. Game secrets are server-side credentials — they should never appear in a browser, mobile app binary, or any client-shipped code. Call this endpoint from your game's backend, not directly from a player's device. The response is automatically scoped to your game — you cannot use this endpoint to enumerate wallet emails for players that have no Player row in your game. Cross-game lookups return 404 , intentionally indistinguishable from "player doesn't exist anywhere." Response shape Success (200) — wallet-bound player { "status": "success", "player_email": "alice@example.com", "player_phone": "+15551234567", "wallet_user_id": "9f3e2d1c-4b5a-6c7d-8e9f-0a1b2c3d4e5f", "primary_phone": "+15551234567", "primary_email": "alice@example.com", "is_minor": false, "emails": [ { "email": "alice@example.com", "primary": true, "verified_at": "2026-04-12T19:21:00+00:00" }, { "email": "alice.work@example.com", "primary": false, "verified_at": "2026-04-15T11:08:00+00:00" }, { "email": "alice.gaming@example.com","primary": false, "verified_at": null } ] } Success (200) — legacy player without wallet Players created before the wallet rollout (2026-05-04) may not have a wallet binding yet. The endpoint gracefully degrades to a single-email payload: { "status": "success", "player_email": "legacy@example.com", "player_phone": "+15551234567", "wallet_user_id": null, "primary_phone": "+15551234567", "primary_email": "legacy@example.com", "is_minor": false, "emails": [ { "email": "legacy@example.com", "primary": true, "verified_at": null } ], "message": "Player has no wallet binding." } Errors Status When Body 401 X-Game-Secret-Key missing or unknown { "status": "error", "message": "Invalid game secret." } 400 Neither player_email nor player_phone provided Descriptive 400 error 400 Phone provided but fails E.164 validation "Invalid 'player_phone' format..." 404 Player not in your game (intentionally same as "not on network") "Player not found in this game." 429 Rate-limited (60 requests/minute per IP) Standard rate-limit response Privacy and scope What you cannot do with this endpoint Look up wallets for phones / emails that have never been in your game Enumerate across the network using a sequence of phone numbers Distinguish between "player exists in another game" and "player doesn't exist" — both return 404 See the guardian relationship for a minor account beyond the is_minor flag — guardian_wallet_user_id is intentionally not exposed The 404 responses are uniform on purpose. A site-wide list of every phone+email-wallet pair would be a phishing primitive; refusing to confirm or deny existence outside your own game prevents that. Implementation tips Cache aggressively per session. The wallet email list changes infrequently — fetch once after login and reuse for the player's session unless they explicitly add or remove an email. Render the primary: true email first. Treat it as the canonical user identity in your UI. Treat verified_at: null as pending. An email with no verified timestamp was added via phone-share OTP but never finished the second-factor confirmation — visually distinguish it from a fully verified email. Don't store the response client-side beyond the session. Wallet email lists are sensitive — keep them in memory or short-lived storage, never localStorage long-term. Sort client-side if you care about order. Response order is currently DB-insertion order and is not part of the API contract. Quick start # Look up by email curl -H "X-Game-Secret-Key: your_game_secret_key_here" \ "https://invo.network/api/wallet/identities?player_email=alice@example.com" # Look up by phone (E.164) curl -H "X-Game-Secret-Key: your_game_secret_key_here" \ "https://invo.network/api/wallet/identities?player_phone=%2B15551234567"

---

## Webhooks

URL: https://docs.invo.network/docs/webhooks

Receive signed, real-time webhook events from Invo (purchase.completed, transfer.received, item.purchased, refunds). HMAC-SHA256 signature verification, idempotency-key de-duplication, retry/backoff, dead-letter and secret rotation.

Webhooks Invo pushes a signed HTTPS request to your server the moment something happens on your game — a purchase clears, a transfer is received, an item is bought, a refund is issued. Webhooks let you react in real time instead of polling. The receiver contract in one breath Expose one HTTPS endpoint. On each request: verify the X-Invo-Signature , de-duplicate on X-Invo-Idempotency-Key , do your work, and return a 2xx quickly . Delivery is at-least-once — the same event may arrive more than once, so your handler must be idempotent. Anything that isn’t a 2xx is retried with exponential backoff. 1. Set up your endpoint Register the HTTPS URL Invo should call, and the events you care about, using the same X-Game-Secret-Key: ivsdk_… your server already sends on every other call — no separate dashboard login needed. We return a signing secret exactly once at creation; store it securely (you can’t retrieve it again, only rotate it). Create / update your webhook subscription (PUT) # Register or update your endpoint + the events you subscribe to. # RECOMMENDED: use ["*"] to receive every event type — then filter server-side. # If you subscribe to a SUBSET, you MUST include "transfer.claim_pending" to be # told an inbound transfer/send is awaiting your player's claim (the #1 gap — # without it, your app never learns there's something "to collect"). curl -X PUT https://api.invo.network/api/dev/webhooks/games/<GAME_ID> \ -H "X-Game-Secret-Key: ivsdk_<your_sdk_key>" \ -H "Content-Type: application/json" \ -d '{ "target_url": "https://your-server.com/invo/webhooks", "subscribed_events": ["*"] }' # Response — signing_secret is returned ONCE, on first creation. Save it now; # POST .../rotate-secret later to roll it. # { # "success": true, # "created": true, # "signing_secret": "<long-random-string>", // store this securely # "subscription": { ... } # } Your target_url must be https and must resolve to a public address — Invo blocks delivery to internal / loopback / cloud-metadata addresses. This is just the create call. For rotate-secret, tuning (timeouts, retries, rate limit, gzip), delivery history, and replay, see the full Webhook Management API — all callable server-to-server with the same X-Game-Secret-Key . 2. Event types Event Fires when purchase.completed A currency / item purchase cleared on any payment method and the player was credited. purchase.failed A purchase attempt failed (card declined, abandoned 3-D Secure, cancelled). Card payments only. purchase.refunded A purchase was refunded (full or partial); the player balance was debited. purchase.disputed A card chargeback / dispute changed state (carries a dispute_status field, e.g. "lost"). Card payments only. purchase.dispute_lost Reserved — schema-defined but not currently emitted; a lost dispute arrives as purchase.disputed with dispute_status="lost". purchase.fraud_warning A pre-dispute fraud warning was raised on a charge. Card payments only. transfer.sent A cross-game transfer was initiated from a player transfer.received A transfer was credited to the destination player transfer.claim_pending An inbound transfer/send is awaiting your player’s claim — subscribe to this to drive your "you have X to collect" notification. Fires to BOTH tenants (direction: outbound for the sender, inbound for the recipient). Omitting it is the most common integration gap. transfer.claim_expired An unclaimed transfer expired transfer.refunded An expired/unclaimed transfer was refunded to the sender item.purchased A player spent currency on one of your in-game items payout.status_changed A partner payout moved to a new lifecycle state balance.updated Reserved — schema-defined but not currently emitted; balance changes surface through the purchase.* / transfer.* events above. webhook.test A test event you triggered from the dashboard Recipient attribution on inbound transfers/sends When you are the destination tenant, the inbound transfer.claim_pending ( direction: "inbound" ) and the GET .../ {id} /status response carry two fields so you can route a "you have X to collect" notice to the right user: • to_phone — the recipient's phone (canonical). Match it to your player.player_phone to find the account to notify. This is your primary key — always match on it first. • to_identity_id — that player's opaque, stable identity (the same id the SDK uses), present only when the phone resolves to a single player. A convenience for an exact match; to_phone is the field you can always rely on. How to read the two fields together: • to_phone set + to_identity_id set → exactly one of your players owns this number. Badge that player. • to_phone set + to_identity_id null → the recipient IS your player, but the number is shared by more than one of your accounts. Still surface it — match to_phone to the logged-in player and show the "to collect" badge. (We withhold only the single identity, never the whole notification — don't treat this as "nothing arrived.") • both null → the recipient has no account on your tenant yet; they onboard via the claim code (no in-app session to badge). ⚠️ Common mistake: treating a null to_identity_id as "no recipient." If to_phone is present, a real transfer is waiting — match on the phone. These fields are delivered to the destination tenant only — never the source. Discovering what's waiting — list the inbound pending claims The webhook is a wake-up , not the source of truth. To render a "you have X to collect" badge you need to ENUMERATE what's waiting for a player — the webhook only tells you something changed, and GET .../ {id} /status needs an id you already have. Use the list endpoint: # Game-secret authed (server-to-server). Pass the player's email OR phone. GET /api/transfers/inbound-pending?player_email=player@example.com -H "X-Game-Secret-Key: <your_secret>" # → only LIVE, unclaimed transfers/sends addressed to THIS player at YOUR game: { "inbound_pending": [ { "transaction_id": "TXN...", "flow": "transfer", // or "send" "amount": "10000.00", "net_amount": "9000.00", // what the recipient receives "source_game_id": "97288428282", "source_game": "AtheraPlay", "to_phone": "+15617675671", // match to the logged-in player "to_identity_id": "id_...", // null if the phone maps to >1 of your players "created_at": "...", "claim_code_expires_at": "..." } ] } The pattern (what every receiving integration should do): 1. On transfer.claim_pending (or on app open / foreground), call this endpoint for the active player. 2. Match to_phone to the logged-in player's number → render a "collect" item per row. (Don't require to_identity_id — it's null when the number is shared.) 3. The player collects via the claim code (or the in-app confirm-receipt). The claim code is never in this list — the claimer supplies it. Returns only rows whose destination is your game; never another tenant's. A row drops off the list automatically once it's claimed or expires (24h → auto-refund to the sender). 3. Request shape Every delivery is a POST with a JSON body and these headers: Header Meaning X-Invo-Signature t=<unix_ts>,v1=<hmac> — verify this (section 4). X-Invo-Idempotency-Key De-dupe on this. Stable for a logical event — unchanged across retries and manual replays. X-Invo-Event-Id Unique per delivery row. Changes on replay — don’t dedupe on this. X-Invo-Secret-Version Which signing-secret version signed this (increments on rotation). Content-Encoding gzip only if you opted into compression — decompress before verifying. De-duplicate on X-Invo-Idempotency-Key — never on X-Invo-Event-Id . The event id is unique per delivery row and changes on every retry and replay ; the idempotency key is stable for the logical event. Keying on the event id would make a replay look like a brand-new event and you’d process it twice. Example payload { "event_id": "f3a1c9d2-...-b7", // per-delivery id (changes on replay) "idempotency_key": "f3a1c9d2-...-b7", // stable logical id — DEDUPE ON THIS "event_type": "purchase.completed", "schema_version": "1.0", "created_at": "2026-06-05T12:34:56.000000+00:00", "tenant_id": "123", // your game_id "data": { "transaction_id": "TXN...", "order_id": "ORD_...", "player_email": "player@example.com", "identity_id": "f3a1b8c0d4e5...", "usd_amount": "10.00", "currency_amount": "1000", "currency_name": "GOLD", "new_balance": "4200" // ...event-specific fields per event_type } } 4. Verify the signature The signature is HMAC-SHA256 over the literal string <timestamp>.<raw_body> , keyed with your signing secret, hex-encoded — the standard signed-webhook scheme. Verify against the raw request bytes (never a re-serialized object), use a constant-time compare, and reject timestamps older than 5 minutes to stop replays. During a secret rotation the header carries multiple v1= values — accept if any matches. Node.js / Express verification const crypto = require('crypto'); const express = require('express'); const app = express(); // IMPORTANT: capture the RAW body — signature is over the exact bytes. app.post('/invo/webhooks', express.raw({ type: 'application/json' }), (req, res) => { if (!verifyInvoSignature(req.body, req.get('X-Invo-Signature'), process.env.INVO_WEBHOOK_SECRET)) { return res.status(400).send('bad signature'); } const event = JSON.parse(req.body.toString('utf8')); // De-dupe on the stable idempotency key (survives retries + replays). if (alreadyProcessed(req.get('X-Invo-Idempotency-Key'))) { return res.status(200).send('duplicate'); } // IMPORTANT: log the FULL raw envelope for ANY event you don't yet handle — // before you ACK. A 2xx tells Invo "received, don't retry", so an event your // handler doesn't recognize yet (deployed after it fired, or a type you don't // map) is GONE unless you logged it. Logging only event_type is the #1 way // teams silently lose an inbound "money arrived" event. Keep the raw body. if (!isHandled(event.event_type)) { logUnhandledWebhook({ event_id: event.event_id, idempotency_key: req.get('X-Invo-Idempotency-Key'), event_type: event.event_type, raw: req.body.toString('utf8'), // full payload — recoverable/replayable }); return res.status(200).send('ok (logged unhandled)'); } handle(event); // do your work (ideally async — see section 6) return res.status(200).send('ok'); // 2xx = we won't retry }); function verifyInvoSignature(rawBody, header, secret, toleranceSec = 300) { if (!header || !secret) return false; const t = header.split(',').find(p => p.trim().startsWith('t='))?.split('=')[1]; const sigs = header.split(',').filter(p => p.trim().startsWith('v1=')) .map(p => p.split('=')[1].trim()); if (!t || sigs.length === 0) return false; if (Math.abs(Math.floor(Date.now() / 1000) - Number(t)) > toleranceSec) return false; // replay guard const expected = crypto.createHmac('sha256', secret) .update(Buffer.concat([Buffer.from(t + '.'), rawBody])) .digest('hex'); return sigs.some(s => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected))); } 5. Retries & at-least-once delivery If your endpoint doesn’t return a 2xx (timeout, 5xx, connection error), Invo retries with exponential backoff. After the schedule is exhausted the event is moved to a dead-letter queue, where it can be replayed manually once your endpoint is healthy. Backoff schedule 30s → 2m → 10m → 1h → 6h → 24h (6 attempts), each with a little jitter, then dead-letter. Why dedupe matters A retry — or an admin replay — re-sends the same logical event with the same X-Invo-Idempotency-Key . Keying your processing on it makes double-delivery a no-op. 6. Secret rotation Rotating your signing secret returns a new one and keeps the old one valid for a 7-day grace window . During that window every delivery is signed with both secrets (two v1= values), so you can roll over with zero dropped events: deploy the new secret, then let the old one expire. The X-Invo-Secret-Version header tells you which version is current. Receiver checklist Serve the endpoint over HTTPS on a public address. Verify X-Invo-Signature against the RAW body, constant-time, 5-min tolerance. De-duplicate on X-Invo-Idempotency-Key (not X-Invo-Event-Id). Return 2xx fast — offload slow work to a queue; we time out around 10s. Treat delivery as at-least-once: make your handler idempotent. Store your signing secret securely; rotate it without downtime via the grace window.

---

## Webhook Management API

URL: https://docs.invo.network/docs/webhook-management
Endpoint: PUT /api/dev/webhooks/games/{game_id}

Manage webhook subscriptions server-to-server with your X-Game-Secret-Key: create/update, rotate the signing secret, fire test events, view delivery history and metrics, replay dead-letters, and tune timeouts/retries/rate-limit/gzip.

Webhook Management API Create, inspect, tune, and replay your webhook subscription — all server-to-server with the same X-Game-Secret-Key you already use. No dashboard login required. Authentication Every endpoint below accepts your game’s X-Game-Secret-Key: ivsdk_… — the canonical server-to-server credential, identical to every other Invo API call. (The partner dashboard uses a session token for the same operations; you don’t need it.) The key’s game must be active, and a key can only manage its own game’s webhooks. Endpoint summary Base path: /api/dev/webhooks Method Path Purpose GET /supported-events List every event type the schema defines (a few are reserved and not currently emitted — see the Webhooks page) GET /games/{game_id} Current subscription + recent deliveries PUT /games/{game_id} Create or update the subscription DELETE /games/{game_id} Disable (soft-delete) the subscription POST /games/{game_id}/rotate-secret Rotate the signing secret (7-day grace) POST /games/{game_id}/test Fire a synthetic webhook.test event GET /games/{game_id}/metrics Delivery metrics + health state PATCH /games/{game_id}/retry-policy Per-subscription tuning overrides GET /games/{game_id}/deliveries Paginated delivery history GET /deliveries/{delivery_id} Full payload + response body for one delivery POST /deliveries/{delivery_id}/replay Re-enqueue a failed/dead delivery Subscription lifecycle PUT /api/dev/webhooks/games/{game_id} Create or update. Body: { target_url, subscribed_events } ( subscribed_events is ["*"] or a subset of the supported list). Returns 201 on first creation (with the one-time signing_secret ) or 200 on update. Updating also re-enables a disabled subscription. PUT response (first creation) { "success": true, "created": true, "signing_secret": "<long-random-string>", // shown ONCE — store it "signing_secret_note": "Store this signing_secret now — it cannot be retrieved later...", "subscription": { /* subscription object — see contracts below */ } } POST /api/dev/webhooks/games/{game_id}/rotate-secret Mint a new signing secret. The old one stays valid for a 7-day grace window (until previous_secret_expires_at ), during which deliveries are signed with both. Returns the new signing_secret once. DELETE /api/dev/webhooks/games/{game_id} Soft-delete — sets is_active=false . The row and its delivery history are kept for audit; re-create with PUT to re-enable. Returns { success, subscription } . POST /api/dev/webhooks/games/{game_id}/test Enqueue a synthetic webhook.test event to confirm your endpoint verifies signatures and returns 2xx. Returns { success, delivery_id, event_id, note } ; the worker fires it within ~10s — watch /deliveries . Observability & replay GET /api/dev/webhooks/games/{game_id}/deliveries Paginated history. Query params: status ( all|pending|in_progress|succeeded|failed|dead ), event_type , page (default 1), per_page (default 25, max 100). Returns { success, items: [delivery], pagination: { page, per_page, total, total_pages } } . GET /api/dev/webhooks/deliveries/{delivery_id} The full record for one delivery, including the payload we sent and the last_response_body your endpoint returned — use it to debug a failure. POST /api/dev/webhooks/deliveries/{delivery_id}/replay Re-enqueue a failed or dead delivery. We clone the row with a new event_id but the same idempotency_key , so your dedup still works. Re-enable the subscription first if it’s disabled ( 409 ). Capped per logical event ( 409 with redrive_count once exhausted). Replay response { "success": true, "replay_delivery_id": 90142, "replay_event_id": "a1b2c3d4-...", "original_delivery_id": 90011 } GET /api/dev/webhooks/games/{game_id}/metrics Delivery metrics over the last 24h / 7d plus the rolled-up health_state . Drives the dashboard’s health card. Metrics response { "success": true, "health_state": "healthy", // "never" | "healthy" | "failing" "metrics": { "success_rate_24h": 0.987, // 0..1, or null if no data "success_rate_7d": 0.991, "deliveries_24h": 1543, "deliveries_7d": 10872, "dead_count_24h": 2, "dead_count_7d": 9, "p50_ms_24h": 142, // round-trip latency percentiles "p95_ms_24h": 488, "recent_failure_count": 0, // last 60 min "pending_count": 3, "first_attempt_at": "2026-05-29T...", "last_attempt_at": "2026-06-05T..." } } Response object contracts Subscription object Field Notes subscription_id / game_id Identifiers target_url, subscribed_events, is_active Your current config secret_version Integer; increments on every rotate-secret. Matches the X-Invo-Secret-Version header. secret_rotated_at, previous_secret_expires_at Rotation timing; previous_secret_expires_at is null outside a grace window. health_state "never" | "healthy" | "failing" timeout_seconds_override, max_attempts_override Retry-policy overrides (null = platform default) max_deliveries_per_minute, compress_payloads Rate limit + gzip opt-in last_success_at, last_failure_at Most recent outcomes Delivery object status is one of pending → in_progress → succeeded | failed | dead . Fields: delivery_id, event_id, event_type, status, attempts, last_response_code, last_error, next_retry_at, created_at, last_attempted_at, succeeded_at . The single-delivery endpoint adds payload and last_response_body . Per-subscription tuning PATCH /api/dev/webhooks/games/{game_id}/retry-policy Override platform defaults for just your subscription. Send any subset; pass null to clear an override. Field Range Effect timeout_seconds 1–60 How long we wait for your 2xx before counting a failure. max_attempts 1–12 Retries before a delivery is dead-lettered. max_deliveries_per_minute 1–600 Throttle to protect a fragile receiver. A throttled delivery stays pending — it does not consume a retry attempt. compress_payloads bool gzip bodies ≥ 1 KB with Content-Encoding: gzip . Only enable if your receiver decodes gzip (it returns 415 otherwise). Verify the signature against the decompressed body. Leave these unset to use the platform defaults — backoff 30s → 2m → 10m → 1h → 6h → 24h (6 attempts), 10s timeout, no throttle, no compression. The defaults are tuned for most receivers. See also For the receiver side — signature verification, de-duplication, and the at-least-once contract — see Receiving Webhooks .

---

## Platform Partners

URL: https://docs.invo.network/docs/partners

Non-gaming platform partner integration: branded currency, hosted checkout, cross-tenant transfers, and programmatic payouts.

Platform Partners INVO Network supports non-gaming platform partners — video, microdrama, social, creator, and other digital experiences — that want to use INVO as their payment rail and ledger. This page is a high-level overview for partner teams. The technical onboarding contracts are negotiated individually. Who is this for? Companies running consumer apps that want a turnkey way to: • Sell a branded in-app currency to their users with real money • Have users spend that currency on items, unlocks, or subscriptions inside the platform • Let users move balances across the broader INVO Network • Cash out the platform's earned revenue to their bank account Platform status is now self-serve : any KYC-verified developer can claim it for an active game from the Platform & Keys page in the developer dashboard (see below). Negotiated fee splits and custom contracts still start with the contact at the bottom of this page. Self-serve setup — Platform & Keys Everything below is done from the Platform & Keys page in the developer dashboard — sign in at console.invo.network (or dev.console.invo.network for sandbox), open the user menu in the top-right corner, and choose Platform & Keys . 1 Claim platform status Pick your game, then under Platform status choose Video platform , Creator platform , or Social platform and apply. The change is instant — no approval queue. Two requirements: your developer account must be identity-verified (KYC) and the game must be live or testing . Platform tenants are reachable as a transfer destination from every game on the network, so every claim is audited. Choosing Standard game reverts it. 2 Get your SDK secret key The SDK secret key card lets you reveal and copy your ivsdk_… key, and rotate it at any time. Rotation has a 7-day grace window — the old key keeps working while you cut your integration over. See Partner Credentials & Key Handling for the handling rules. 3 Web platforms: turn on passkey step-up Under Passkey step-up , submit the domain your sign-in pages run on and prove you control it with a DNS TXT record — the config goes live the moment verification passes. Full walkthrough on Platform Step-Up (WebAuthn / Passkeys) . 4 Configure your webhook The console links straight to the dashboard's Webhooks page for your game — endpoint URL, event selection, signing secret, and delivery history live there. Contract details: Receiving Webhooks . What Partners Get Branded currency You name the currency (e.g., your platform's "Stars," "Tokens," "Credits"). The network rate is fixed at 1 USD = 10 units; the brand is yours. Hosted checkout Card data never crosses your servers. Partners are SAQ-A scope. We handle PCI, 3DS, and the dispute lifecycle end-to-end. Cross-tenant transfers Your users can move balances between your platform and other tenants on the network. Two flows: self-transfers (same human, two tenants) and player-to-player sends (gifting by phone). SMS PIN on send, claim on receive, settlement happens server-side; you receive an authoritative webhook on every completion. Outbound webhooks HMAC-signed deliveries for every state change — purchases, refunds, transfers, payout status. Replay-safe and dedupable on event id. Transparent revenue split The default network fee is 10% on each item-purchase transaction (90% to the partner). Per-partner overrides are negotiated as part of the agreement and applied to your tenant configuration. Programmatic payouts Request a payout of your accrued revenue at any time via API. We dispatch the bill internally, ACH the funds to your bank, and notify your webhook on every status transition. Web step-up (passkeys) Web platforms verify high-value transfers and sends in-browser with a WebAuthn passkey — phishing-resistant, hardware-bound, and user-verified — instead of an SMS code. Hosted on your own origin. Platform Step-Up → Cross-tenant transfers & sends Once your partner tenant is provisioned, your users can move their branded-currency balance to and from any other live tenant on the network — same REST API gaming-tier developers use. Self-transfer A user moves their own balance from your platform to a destination tenant where they're also a user. Three calls: initiate-transfer → verify-sms (sender PIN) → destination tenant calls claim-transfer with the claim code. Transfer API docs → Player-to-player send Phone-based gifting. Recipient may not exist on Invo yet — they get an SMS with a claim code. Three calls: initiate-send → verify-sms (sender PIN) → recipient tenant calls claim-currency . Send API docs → Verify in-browser with passkeys (web platforms) Web platforms don't have to send an SMS PIN to verify a transfer or send. Once your relying-party domain is configured, users approve a high-value action with a WebAuthn passkey (Touch ID / Windows Hello / a security key) bound to the specific transaction — phishing-resistant and hardware-backed. It's additive: SMS stays as the fallback, and the rest of the lifecycle is unchanged. See Platform Step-Up (WebAuthn / Passkeys) . How transfer fees work for partners User always pays a 10% network fee on the transfer amount. Default split: • 3.5% to the source tenant • 3.5% to the destination tenant • 3% to Invo (network fee) Your tenant has a transfer_fee_percentage setting (default 3.5%) that governs your kickback. A negotiated rate above 3.5% is absorbed from Invo's 3% slice — the user-paid total stays at exactly 10%, and the destination tenant's kickback is unaffected. Read the actual numbers from fee_breakdown in the API response and fee_total in the webhook payload — don't recompute client-side. Transfer policy on your tenant Three flags Invo admin sets on your tenant during onboarding: • allows_outgoing_transfers — your users can send out • allows_incoming_transfers — other tenants' users can send in • universal_transfers — 'yes' to allow any active tenant; 'no' to whitelist specific ones via linked_game_ids[] Always call POST /api/transfers/available-destinations first to discover which destinations are reachable from your tenant before showing options to the user — don't hardcode destination ids. How Partner Integration Works 1 Kickoff & agreement Initial scoping call, ToS and revenue split agreed, designated technical contact identified on each side. 2 Sandbox provisioning Register your game in the sandbox dashboard, claim platform status on the Platform & Keys page, and copy your sandbox SDK key from the same page. Configure your webhook receiver URL on the dashboard's Webhooks page — the signing secret is shown once on creation. INVO stands up your branded currency. 3 Build against sandbox Your engineering team integrates against the same REST API documented elsewhere on this site. Hosted checkout, item purchase, and webhook handling are the same contracts that gaming-tier developers use. 4 Soak window Run real flows in sandbox for a typical 2–4 week QA window before flipping to production. Reconciliation diffs should match your internal ledger nightly. 5 Production cutover Repeat the same self-serve setup on the production console (Platform & Keys for the SDK key, Webhooks page for the signing secret). Swap your base URL, run a small live transaction set, and you're live. Partner Payouts As your users top up and spend, your tenant accrues revenue (the default 90% partner share on every item purchase, plus any custom rate negotiated in your agreement). You can request a payout at any time: What you send • Amount in USD (must be ≤ current owed balance) • Contact email for status updates • Destination ACH bank details (sent on each request) • Idempotency key so retries don't double-pay What happens next • INVO admin reviews the request • On approval, an internal bill is created and ACH'd • Your webhook receives payout.status_changed events at every transition ( requested → approved → processing → completed ) • Your owed balance decrements by the paid amount Account numbers are encrypted at rest; only the last four digits ever appear in API responses or webhook payloads. What's the same as the gaming-tier API Partners use the same REST API that gaming-tier developers use: Same auth. Single X-Game-Secret-Key header on every server-to-server call. Same hosted checkout. Mint a session, open the URL, listen for the webhook. Same item-purchase flow. POST /api/item-purchases/purchase-item with idempotency-keyed bodies. Same balance reads. Single, batch, and streaming reconciliation endpoints. Same webhook envelope. HMAC signature, retry policy, idempotency on event id. The technical pages on this site ( Authentication , Currency Purchase , Item Purchase , Player Balance ) all apply directly. What's different for partners is the business agreement, the branded-currency setup, and the payout flow described above. Talk to us Partner onboarding starts with a conversation. Tell us what you're building, the volume you expect, and what shape you'd want the integration to take. partners@invo.network

---