Integration Documentation

Ye docs un developers ke liye hai jo NS Gaming use karke apni website par games launch karna chahte hain. Neeche auth, launch request, callbacks aur ready code snippets diye gaye hain.

Base Flow

1) Dashboard se API keys lo → 2) Launch API hit karo → 3) payload.game_launch_url ko iframe/new tab me open karo → 4) Bet/win callbacks server par process hote hain.

Security

Kabhie bhi apni Secret Key client-side (Javascript) mein expose na karein. Hamesha server-to-server call karein.

1) Authentication

Har user/reseller ko dashboard se do cheezein milti hain: API_KEY aur SECRET_KEY.

API_KEY SECRET_KEY

API_KEY: Requests authorize karne ke liye. Aap Authorization: Bearer {API_KEY} ya X-API-Key: {API_KEY} use kar sakte ho.

SECRET_KEY: Launch API me extra security ke liye X-API-Secret: {SECRET_KEY} header me bhejein (reseller keys ke liye required).

2) Game Launch API (The Request)

Game launch karne ke liye server-to-server request bhejo. Response me payload.game_launch_url milega (isko open karo).

POST
https://ns-api.space/api/v1/launch.php

Headers

Authorization: Bearer {API_KEY}
X-API-Secret: {SECRET_KEY}
Content-Type: application/json

Body (JSON)

{
    "player_id": 1,
    "game_uid": "GAME_UID_HERE",
    "language": "en",
    "platform": 1
}

Response

{
    "code": 0,
    "msg": "ok",
    "payload": {
        "game_launch_url": "https://ns-api.space/play.php?id=...",
        "inline_launch_url": "https://provider-domain.com/launch?...",
        "expires_at": "2025-12-29 10:20:30",
        "provider_http_status": 200
    }
}

Try it out (Server-to-Server)

Ye page server-side se call karta hai, isliye aapka API_KEY/SECRET_KEY client-side par expose nahi hota.

(Aapka API Key jo dashboard se mila hai)
(Aapka Reseller API Secret key)
(Website users table ka active User ID)
(Game code jaise Plinko ya ande/slots code)

3) Seamless Callback (The Integration)

Game provider aapke panel/server par callback hit karta hai taaki bet/win ke according wallet update ho sake. Aapko apni website par callback endpoint banane ki zarurat nahi hoti.

Callback URL (Server)

Provider ko jo callback URL send hota hai, wo config se aata hai. Recommended: GAME_API_CALLBACK_URL ko set karke Laravel route use karein.

Recommended

GAME_API_CALLBACK_URL=https://your-domain.com/api/callback/seamless
Security: Provider IP allowlist PROVIDER_TRUSTED_IPS se control hoti hai (comma-separated IPs/CIDRs).
POST
https://your-domain.com/api/callback/seamless

Sample JSON (provider → your server)

{
    "agency_uid": "AGENCY_UID",
    "timestamp": 1735360000000,
    "payload": "BASE64_ENCRYPTED_PAYLOAD..."
}

Response Codes

Code Meaning When to use
0 Success Callback processed + balance updated
10025 Insufficient User/reseller balance insufficient (reject bet)

4) Code Snippets

Copy-paste ready examples.

PHP (cURL) — Launch Game

<?php
$endpoint = 'https://ns-api.space/api/v1/launch.php';
$apiKey = 'YOUR_API_KEY';
$secretKey = 'YOUR_SECRET_KEY';

$body = [
  'player_id' => 1,
  'game_uid' => 'GAME_UID_HERE',
  'language' => 'en',
  'platform' => 1,
];

$ch = curl_init($endpoint);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  'Authorization: Bearer ' . $apiKey,
  'X-API-Secret: ' . $secretKey,
  'Content-Type: application/json',
  'Accept: application/json',
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($body, JSON_UNESCAPED_SLASHES));
$resp = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($resp === false) {
  throw new RuntimeException(curl_error($ch));
}
curl_close($ch);

echo "HTTP: " . $httpCode . "\n";
echo $resp . "\n";

Node.js (Axios) — Launch Game

import axios from "axios";

const endpoint = "https://ns-api.space/api/v1/launch.php";
const apiKey = "YOUR_API_KEY";
const secretKey = "YOUR_SECRET_KEY";

const body = {
  player_id: 1,
  game_uid: "GAME_UID_HERE",
  language: "en",
  platform: 1,
};

const res = await axios.post(endpoint, body, {
  headers: {
    Authorization: `Bearer ${apiKey}`,
    "X-API-Secret": secretKey,
    "Content-Type": "application/json",
    Accept: "application/json",
  },
  timeout: 20000,
});

console.log(res.status, res.data);

Config — Callback IP Allowlist

PROVIDER_TRUSTED_IPS=127.0.0.1,::1
CALLBACK_MAX_SKEW_SECONDS=300

5) Merchant Integration Kit (Wallet Setup)

Agar aap dusri websites (merchants) ko games provide kar rahe hain, toh aap unhe `/kit` folder ki files de sakte hain. Merchant ko is folder ko apne server par upload karna hoga aur use configure karna hoga.

1. Dynamic URL Routing (.htaccess)

Merchant website me game list, category aur launch URLs bina .php extension ke load hote hain. Kit ke andar maujood .htaccess file automatically extensionless URLs (jaise /GetThirdGameCategory) ko redirect kar deti hai.

Agar server **Nginx** hai, toh client server-admin ko niche diya rewrite rule configuration me add karna hoga:

location /api/webapi/ {
    try_files $uri $uri/ $uri.php$is_args$args;
}

2. Custom Wallet Integration (config.php)

Merchant ko apne database credentials aur wallet tables ko map karne ke liye kit/config.php me diye gaye functions ko edit karna hoga:

A. Fetch Player Balance

Game launch karne aur callback balance verification ke liye players ka real-time balance return karein:

function get_player_balance($conn, int $userId): ?float {
    // Apne users table aur balance column se map karein
    $stmt = $conn->prepare("SELECT balance FROM users WHERE id = ? LIMIT 1");
    if (!$stmt) return null;
    $stmt->bind_param("i", $userId);
    $stmt->execute();
    $res = $stmt->get_result();
    if (!$res || $res->num_rows == 0) {
        $stmt->close();
        return null;
    }
    $balance = round(floatval($res->fetch_assoc()['balance']), 2);
    $stmt->close();
    return $balance;
}

B. Update Player Balance

Bet/win callbacks ke douran player ka balance database me edit karne ke liye:

function update_player_balance($conn, float $newBalance, int $userId): bool {
    // Apne users table aur balance column se map karein
    $stmt = $conn->prepare("UPDATE users SET balance = ? WHERE id = ?");
    if (!$stmt) return false;
    $stmt->bind_param("di", $newBalance, $userId);
    $ok = $stmt->execute();
    $stmt->close();
    return $ok;
}

C. Verify Active Session

Unauthenticated and fake launch requests ko block karne ke liye user session key ko database me match karein:

function verify_active_session($conn, string $token): bool {
    // Apni sessions/users table me token key verify karein
    $stmt = $conn->prepare("SELECT 1 FROM users WHERE token = ? LIMIT 1");
    if (!$stmt) return true;
    $stmt->bind_param("s", $token);
    $stmt->execute();
    $res = $stmt->get_result();
    $active = ($res && $res->num_rows > 0);
    $stmt->close();
    return $active;
}

6) Error Codes

Common codes aapko launch API aur callback flow me mil sakte hain.

Code Meaning Action
0 Success Continue flow
10025 Insufficient Stop request / show insufficient balance
1 General error Log server-side and retry only if safe