# Invo Network API Documentation - Complete Reference

Invo Network is a cross-game currency and player transfer system for game developers. It enables secure value transfers between games, player-to-player currency sends, real-money purchases, and comprehensive player balance management supporting 60M+ users.

Website: https://ourinvo.com
Documentation: https://docs.invo.network
Production API: https://invo.network/api
Sandbox API: https://sandbox.invo.network/sandbox/api
Developer Console: https://console.invo.network
Sandbox Console: https://dev.console.invo.network

---

## Base URLs

- Production API: https://invo.network (routes: /api/*, /auth/*)
- Sandbox API: https://sandbox.invo.network (routes: /sandbox/api/*, /sandbox/auth/*)
- Console (Production): https://console.invo.network
- Console (Sandbox): https://dev.console.invo.network

---

## Authentication

Invo Network uses JWT (JSON Web Token) authentication.

- Game clients authenticate with SDK keys (Bearer tokens).
- SDK key format: ivsdk_[64-character-random-string]
- Authentication header: X-Game-Secret-Key: your_game_secret_key_here (or Authorization: Bearer ivsdk_key_here)
- Web dashboards additionally require CSRF tokens.

Login endpoint:
- Production: POST https://invo.network/auth/login
- Sandbox: POST https://sandbox.invo.network/sandbox/auth/login
- Request body: { "email": "string", "password": "string" }

CSRF token endpoint:
- Production: GET https://invo.network/auth/csrf-token
- Sandbox: GET https://sandbox.invo.network/sandbox/auth/csrf-token

---

## Quick Start

1. Register at https://console.invo.network (production) or https://dev.console.invo.network (sandbox)
2. Create your game via the 4-step game wizard
3. Get your auto-generated SDK key (format: ivsdk_[64-char])
4. Configure virtual currencies (name, symbol, starting amount, transfer limits)
5. Make your first API call to check a player balance

First API call example:
POST /sandbox/api/player-balances/check
Header: X-Game-Secret-Key: your_sdk_key
Body: { "player_email": "test@example.com", "game_secret": "your_sdk_key" }

---

## Game Registration

Register your game through the console wizard at console.invo.network:
1. Enter game details (name, description, genre)
2. Configure virtual currency
3. Get auto-generated SDK key
4. Set transfer policies

---

## Player Management API

APIs optimized for 60M+ players with caching, circuit breakers, and streaming.

### Get Player Balance by Email
GET /api/player-balances/player/by-email/{email}
Header: X-Game-Secret-Key: your_game_secret_key_here
Rate Limit: 1,500 requests/minute per game

Response:
{
  "player": {
    "player_id": 12345,
    "player_name": "John Doe",
    "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": "100.00",
      "total_balance": "1600.00"
    }
  ],
  "summary": {
    "total_value": "1600.00",
    "currency_count": 1,
    "has_funds": true
  },
  "last_updated": "2024-12-09T12:34:56Z"
}

### Get Player Balance by ID
GET /api/player-balances/player/{player_id}
Header: X-Game-Secret-Key: your_game_secret_key_here

### Batch Balance Query
POST /api/player-balances/batch
Header: X-Game-Secret-Key: your_game_secret_key_here
Rate Limit: 100 requests/minute per game
Supports up to 50,000 players per batch (chunk_size parameter).

### Stream All Balances
GET /api/player-balances/stream-all
Header: X-Game-Secret-Key: your_game_secret_key_here
Rate Limit: 5 requests/hour
Server-Sent Events stream for real-time balance data.

### Game Summary
GET /api/player-balances/game-summary
Header: X-Game-Secret-Key: your_game_secret_key_here

### Balance Webhook
POST /api/player-balances/webhook/balance-updated
Configure webhooks for real-time balance change notifications.

---

## Virtual Currency Setup

Configure currencies through the console at console.invo.network:
- Currency Name (e.g., "Gold Coins")
- Currency Symbol (e.g., "GC")
- Symbol URL (icon image)
- Starting Amount (balance for new players)
- Transferable (enable/disable cross-game transfers)
- Minimum Transfer Amount
- Maximum Transfer Amount
- Currency Type: default, premium, seasonal, or achievement

Supported icon formats: PNG, JPG, SVG (64x64px or 128x128px recommended, max 2MB).

---

## Currency Purchase (Hosted Checkout)

Enable real-money purchases via Invo Network's Stripe-powered hosted checkout. No payment UI development required.

Checkout URL pattern:
https://console.invo.network/stripe-checkout/?game_secret=YOUR_SDK_KEY&player_email=player@example.com&usd_amount=50.00

Integration: Open URL in iframe or WebView. Listen for postMessage events:
- Event type: INVO_CHECKOUT_COMPLETE
- Data: { status, currency_received, new_balance }

Features:
- PCI DSS Level 1 compliance
- 3D Secure authentication
- Saved payment methods
- Real-time fraud detection
- Mobile-optimized

---

## Item Purchase API

Purchase in-game items using virtual currency balances.

### Purchase Item
POST /api/item-purchases/purchase-item
Header: X-Game-Secret-Key: your_game_secret_key_here

Request:
{
  "client_request_id": "unique-request-id",
  "player_email": "player@example.com",
  "player_name": "Player Name",
  "item_id": "item-123",
  "item_name": "Epic Sword",
  "item_quantity": 1,
  "unit_price": "100.00",
  "total_price": "100.00",
  "item_category": "weapons"
}

Security: Idempotency via client_request_id. Fraud protection includes:
- Insufficient Balance Lockout: 20 failed attempts triggers 1-hour block
- Rapid Purchase Lockout: 10+ attempts in 1 minute
- General Spam Lockout: 100+ attempts in 5 minutes

### Get Purchase History
GET /api/item-purchases/player-purchase-history
Header: X-Game-Secret-Key: your_game_secret_key_here

### Get Order Details
GET /api/item-purchases/order-details
Header: X-Game-Secret-Key: your_game_secret_key_here

---

## Payment Methods

Supported via hosted checkout (Stripe-powered):
- Credit/Debit Cards: Visa, Mastercard, American Express, Discover, JCB, Diners Club
- Global: 135+ currencies, 195+ countries
- Regional: SEPA, iDEAL, Alipay, WeChat Pay, ACH, Boleto, and more
- Security: 3D Secure (3DS2), PCI DSS Level 1, fraud detection, secure tokenization

---

## Cross-Game Self-Transfers

Transfer your own currency between different games you play. Requires SMS verification.

Fee Structure (10% total):
- Source Game: 3.5%
- Target Game: 3.5%
- Platform: 3.0%

Rate Limits: 10 transfers/hour per player, 5,000 units/day, $5,000/day.

### Flow
1. Get available destinations
2. Initiate transfer (triggers SMS to sender)
3. Verify SMS PIN (6-digit, valid 10 minutes, max 3 attempts)
4. Receive claim code (24-hour expiry, one-time use, phone-locked)
5. Claim transfer in target game

### Available Transfer Destinations
POST /api/transfers/available-destinations
Header: X-Game-Secret-Key: your_game_secret_key_here
Request: { "source_game_id": "string" }

Response includes: game_id, game_name, developer_name, genre, currency_name, currency_symbol, minimum_transfer, maximum_transfer.
Transfer modes: "universal" (all games) or "linked" (specific games).
Cache results for 24 hours.

### Initiate Transfer
POST /api/transfers/initiate-transfer
Header: X-Game-Secret-Key: your_game_secret_key_here (from source game)

Request:
{
  "client_request_id": "unique-id",
  "source_player_name": "Player Name",
  "source_player_email": "player@example.com",
  "source_player_phone": "+1234567890",
  "target_player_phone": "+1234567890",
  "target_game_id": "target-game-id",
  "amount": "500.00"
}

Response: transaction_id, order_id, fees_preview (with net_amount), verification_required details.

### Verify SMS PIN
POST /api/transfers/verify-sms
Request: { "transaction_id": "string", "sms_pin": "123456" }
Response: claim_code, transfer_summary (amount_initiated, net_amount_for_claim, fees_deducted), claim_instructions with expiration.

### Claim Transfer
POST /api/transfers/claim-transfer
Header: X-Game-Secret-Key: your_game_secret_key_here (from target game)

Request:
{
  "claim_code": "string",
  "target_player_name": "Player Name",
  "target_player_email": "player@example.com",
  "target_player_phone": "+1234567890",
  "target_currency_id": "currency-id"
}

IMPORTANT: target_player_phone MUST match the phone set during initiation. Mismatch returns 403 Forbidden.
Automatic player creation if new. 24-hour claim window. Atomic operations.

### Transfer Status
GET /api/transfers/{transaction_id}/status

### Transfer History
GET /api/transfers/transfer-history

---

## Player-to-Player Currency Sends

Send currency to other players via phone number. Works same-game (peer-to-peer) or cross-game.

Fee Structure (10% total):
- Sender Game: 3.5%
- Receiver Game: 3.5%
- Platform: 3.0%

Rate Limits: 25 sends/hour per player, 10,000 units/day.

### Flow
1. Get available send destinations (optional)
2. Initiate send (triggers SMS to sender for verification)
3. Verify SMS PIN
4. Claim code automatically sent to receiver via SMS
5. Receiver claims currency

### Send Destinations
POST /api/currency-sends/available-destinations
Header: X-Game-Secret-Key: your_game_secret_key_here
Request: { "source_game_id": "string" }

Response includes own game (for peer-to-peer) plus other games. This endpoint is optional - existing send APIs work without it.

### Initiate Send
POST /api/currency-sends/initiate-send
Header: X-Game-Secret-Key: your_game_secret_key_here

Request:
{
  "client_request_id": "unique-id",
  "sender_player_name": "Sender Name",
  "sender_player_email": "sender@example.com",
  "sender_player_phone": "+1234567890",
  "receiver_player_phone": "+0987654321",
  "receiving_game_id": "game-id",
  "amount": "250.00"
}

For peer-to-peer (same game): set receiving_game_id to your own game ID.
For cross-game: set receiving_game_id to target game ID.

### Verify Send SMS
POST /api/currency-sends/verify-sms
Request: { "transaction_id": "string", "sms_pin": "123456" }
Response: claim_code, claim_instructions, send_summary, receiver_notified: true.
Key difference from transfers: receiver is automatically notified via SMS with the claim code.

### Claim Sent Currency
POST /api/currency-sends/claim-currency
Header: X-Game-Secret-Key: your_game_secret_key_here (from receiving game)

Request:
{
  "claim_code": "string",
  "receiver_player_name": "Receiver Name",
  "receiver_player_email": "receiver@example.com",
  "receiver_player_phone": "+0987654321"
}

IMPORTANT: receiver_player_phone MUST match the phone set during initiation. Mismatch returns 403 Forbidden.
Automatic new player creation. SMS confirmation sent upon successful claim.

---

## Security Features

- All claim codes are locked to specific phone numbers
- SMS verification required for transfers and sends (6-digit PIN, 10-minute window, max 3 attempts)
- Rate limiting on all endpoints
- Funds reserved atomically until claim or expiration
- Idempotency via client_request_id on all mutation endpoints
- PCI DSS Level 1 compliance for payments
- 3D Secure authentication for purchases
- Real-time fraud detection
- Circuit breakers for reliability

---

## Unity SDK

Official InvoSDK plugin for Unity.

Compatibility: Unity 6 (6000.0+), .NET Standard 2.1
GitHub: https://github.com/Invo-Technologies/Invo-unity-sdk.git

Installation:
1. Clone repository
2. Copy to Assets/InvoSDK/
3. Install com.unity.nuget.newtonsoft-json package
4. Run Setup Wizard: InvoSDK > Setup Wizard

API Methods:
- GetPlayerBalanceAsync(email) - Get player balance
- GetGameItemsAsync() - Get available items
- PurchaseItemAsync(playerEmail, itemId, quantity, unitPrice) - Purchase item
- GetAvailableDestinationsAsync() - Get transfer destinations
- InitiateSendAsync() - Start currency send
- VerifySmsAsync() - Verify SMS PIN
- ClaimCurrencyAsync() - Claim currency

Endpoints:
- Sandbox: https://sandbox.invo.network/sandbox/api/*
- Production: https://invo.network/api/*

Pre-built UI Components: Item Purchase Panel, Featured Items, Transfer Wizard, Send Currency Panel, Window Manager, Verification Input.

---

## Unreal Engine SDK

Official InvoSDK plugin for Unreal Engine.

Compatibility: Unreal Engine 4.27+ and 5.x
GitHub: https://github.com/Invo-Technologies/invo-unreal-sdk.git

Installation:
1. Clone repository
2. Place in YourProject/Plugins/InvoSDK/
3. Enable via Edit > Plugins

Integration Methods:
- Blueprint: InvoSDK | API category nodes
- C++: #include "InvoSDKApiManager.h"

Endpoints:
- Sandbox: https://sandbox.invo.network/sandbox/api/*
- Production: https://invo.network/api/*

Pre-built UMG Widgets: Daily Deals, Featured Items, Item Purchase, Send Currency, Transfer Currency, SMS Verification.

---

## Sandbox Testing

Safe testing environment at sandbox.invo.network. All sandbox routes use /sandbox/ prefix.

- Sandbox Console: https://dev.console.invo.network
- Sandbox API: https://sandbox.invo.network/sandbox/api/*
- Sandbox Auth: https://sandbox.invo.network/sandbox/auth/*

Same functionality as production but isolated data and no real payments.

---

## Complete API Endpoint Reference

### Authentication
- POST /auth/login - Authenticate and get JWT token
- GET /auth/csrf-token - Get CSRF token (web dashboards only)

### Player Balances
- GET /api/player-balances/player/by-email/{email} - Get balance by email
- GET /api/player-balances/player/{player_id} - Get balance by ID
- POST /api/player-balances/batch - Batch balance query (up to 50K)
- GET /api/player-balances/stream-all - Stream all balances (SSE)
- GET /api/player-balances/game-summary - Game balance summary
- POST /api/player-balances/check - Check player balance
- POST /api/player-balances/credit - Credit balance
- POST /api/player-balances/debit - Debit balance
- POST /api/player-balances/webhook/balance-updated - Balance webhook

### Currency Purchases
- Hosted Checkout URL: https://console.invo.network/stripe-checkout/?game_secret=KEY&player_email=EMAIL&usd_amount=AMOUNT

### Item Purchases
- POST /api/item-purchases/purchase-item - Purchase item
- GET /api/item-purchases/player-purchase-history - Purchase history
- GET /api/item-purchases/order-details - Order details

### Cross-Game Transfers
- POST /api/transfers/available-destinations - Get destinations
- POST /api/transfers/initiate-transfer - Start transfer
- POST /api/transfers/verify-sms - Verify SMS PIN
- POST /api/transfers/claim-transfer - Claim transfer
- GET /api/transfers/{transaction_id}/status - Transfer status
- GET /api/transfers/transfer-history - Transfer history
- GET /api/transfers/security-status - Security status

### Player-to-Player Sends
- POST /api/currency-sends/available-destinations - Get destinations
- POST /api/currency-sends/initiate-send - Start send
- POST /api/currency-sends/verify-sms - Verify SMS PIN
- POST /api/currency-sends/claim-currency - Claim currency

---

Provider: Invo Technologies Inc.
Website: https://ourinvo.com
Contact: Support available via developer console