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.