API Documentation

Integration guide for Netspace ONE games. The entire integration process is managed through the Partners Portal.

Integration Process

🏢 Partners Portal

The Partners Portal is your control center for integration. All credentials, webhooks, tests, and certification are managed there.

Portal Features

Integration Steps in Portal

📦 SDKs

Use our official SDKs to quickly integrate Netspace ONE games into your platform. All SDKs handle authentication, game launching, and error handling automatically.

Available SDKs

<script src="https://cdn.netspace.one/sdk/netspace-sdk.js"></script>

const netspace = new NetspaceSDK.NetspaceSDK({
  apiKey: 'your-api-key',
  secretKey: 'your-secret-key'
});

const session = await netspace.launchGame({
  sessionId: 'session-123',
  playerId: 'player-456',
  gameId: 'lotterix',
  currency: 'USD',
  clientIp: '192.168.1.1'
});

netspace.openInIframe('game-container', session.game_url);

composer require netspace/sdk

use Netspace\NetspaceSDK;

$netspace = new NetspaceSDK([
    'apiKey' => 'your-api-key',
    'secretKey' => 'your-secret-key'
]);

$session = $netspace->launchGame([
    'sessionId' => 'session-123',
    'playerId' => 'player-456',
    'gameId' => 'lotterix',
    'currency' => 'USD',
    'clientIp' => $_SERVER['REMOTE_ADDR']
]);

header('Location: ' . $session['game_url']);

pip install netspace-sdk

from netspace import NetspaceSDK

netspace = NetspaceSDK(
    api_key='your-api-key',
    secret_key='your-secret-key'
)

session = netspace.launch_game(
    session_id='session-123',
    player_id='player-456',
    game_id='lotterix',
    currency='USD',
    client_ip=request.remote_addr
)

return redirect(session['game_url'])

<dependency>
    <groupId>one.netspace</groupId>
    <artifactId>netspace-sdk</artifactId>
    <version>1.0.0</version>
</dependency>

NetspaceSDK netspace = new NetspaceSDK(
    "your-api-key",
    "your-secret-key"
);

LaunchResponse session = netspace.launchGame(
    new LaunchGameParams()
        .setSessionId("session-123")
        .setPlayerId("player-456")
        .setGameId("lotterix")
        .setCurrency("USD")
        .setClientIp(request.getRemoteAddr())
);

response.sendRedirect(session.getGameUrl());

SDK Features

Download SDKs

🔐 Authentication

All API communications are signed with HMAC-SHA256.

Required Headers

Signature Calculation

StringToSign = TIMESTAMP + METHOD + PATH + BODY
Signature = HMAC-SHA256(StringToSign, secretKey)

⚠️ Important: The PATH must include the /api prefix (e.g., /api/game/launch)

Example (JavaScript)

const crypto = require('crypto');

function generateSignature(timestamp, method, path, body, secretKey) {
  const stringToSign = `${timestamp}${method.toUpperCase()}${path}${JSON.stringify(body)}`;
  return crypto.createHmac('sha256', secretKey).update(stringToSign).digest('hex');
}

// Example:
const timestamp = Math.floor(Date.now() / 1000).toString(); // Seconds!
const signature = generateSignature(
  timestamp,
  'POST',
  '/api/game/launch',  // Must include /api prefix
  { game_id: 'lotterix', player_id: 'player123' },
  'your-secret-key'
);

📞 Webhook

Your platform must implement a single webhook endpoint to receive all Netspace calls.

Action Types

Request Format

{
  "action_type": "bet",
  "session_id": "your_session_id",
  "player_id": "player123",
  "transaction_id": "txn_123",
  "amount": 10.00,
  "currency": "USD",
  "game_id": "lotterix",
  "round_id": "round_456",
  "timestamp": "2025-01-15T10:30:00.000Z"
}

Response Format

{
  "success": true,
  "balance": 1490.50,
  "transaction_id": "your_internal_txn_id"
}

🎁 Free Bets

Free Bets allow operators to offer promotional credits to players. Players can bet using promotional credits without risking their real balance, but winnings ARE credited to their real balance.

How It Works

Free Bet Endpoints

Assign Free Bet Request

POST /api/v1/freebets/assign

{
  "operator_free_bet_id": "promo_2025_001",
  "player_id": "player123",
  "free_bets": {
    "amount": 50.00,
    "currency": "BRL",
    "expires_at": "2025-02-15T23:59:59Z"
  }
}

Get Free Bet Status

POST /api/v1/freebets/status

{
  "netspace_free_bet_id": "fb_ns_abc123"
}

Cancel Free Bet

POST /api/v1/freebets/cancel

{
  "netspace_free_bet_id": "fb_ns_abc123",
  "reason": "Player requested cancellation"
}

Webhook: Free Bet Transactions

When a player uses a Free Bet, your webhook receives transactions with additional fields:

BET with Free Bet

{
  "action_type": "bet",
  "amount": 10.00,
  "is_free_bet": true,
  "operator_free_bet_id": "promo_2025_001",
  "netspace_free_bet_id": "fb_ns_abc123"
}

⚠️ When is_free_bet: true, do NOT deduct from player's real balance.

WIN from Free Bet

{
  "action_type": "win",
  "amount": 50.00,
  "from_free_bet": true,
  "operator_free_bet_id": "promo_2025_001",
  "netspace_free_bet_id": "fb_ns_abc123"
}

✅ When from_free_bet: true, DO credit to player's real balance.

SDK Methods

✅ Certification

Tests are run from the Partners Portal in Integration > Tests.

Required Tests

Once all required tests pass, you can request production activation from the portal.

🔌 API Endpoints

Game Launch

POST /api/game/launch

Game Endpoints

Catalog Endpoints

Free Bets Endpoints

Jackpot Endpoints

Sandbox Endpoints

Certification Endpoints

💰 Supported Currencies

FIAT (18)

Crypto (15)

🌍 Supported Languages

⚠️ Error Codes

Error Response Format

{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_BALANCE",
    "message": "Player balance is insufficient"
  }
}

📥 Downloads

Download the complete integration documentation in PDF format.