B2B API Integration Guide

Welcome to the Win20X Developer Documentation. Our platform enables seamlessly embedding 100+ top-tier casino game suppliers (including Aviator, Slots, Table Games, and Live dealers) directly into your website via a unified B2B gateway.

This integration is executed in an A-Z flow: retrieving providers, fetching game lists, generating launch links, and processing transactional webhooks on your player ledger.

Key Features

The Win20X B2B API provides a unified, secure gateway to manage casino gaming sessions, provider integrations, and player ledger updates in real-time.

Base URL & Connectivity

All Win20X API queries must be submitted over secure HTTPS connection to the following endpoint:

https://api.win20x.com

Port Configuration: Standard SSL Port 443 is used. Please ensure your backend firewall permits outbound connections to this destination.

Integration Flow

To take a player from your lobby to a live game session, complete these five sequential steps:

API Credentials & Authentication

All outbound API requests from your server to our gateway must connect over HTTPS to https://api.win20x.com and present B2B credentials in the request headers.

Note: API requests will be rejected unless the originating server IP address is whitelisted in your B2B dashboard.

1. Retrieve Game Providers

Fetch all active game suppliers integrated on the SaaS gateway.

Sample Response:

{
  "success": true,
  "message": "All games grouped by provider fetched successfully",
  "games": [
    "SPRIBE",
    "EVOPLAY",
    "PRAGMATIC",
    "ODIN"
  ]
}

2. Retrieve Games List

Retrieve the complete game portfolio mapping of a specific supplier.

Query Parameters:

Sample Response:

{
  "success": true,
  "message": "All games for EVOPLAY fetched successfully",
  "games": [
    {
      "id": "75f81c56565d394503f544f3431ef370",
      "name": "Aviator",
      "provider_name": "SPRIBE",
      "game_type": "crash"
    }
  ]
}

3. Generate Game Session URL

Requests a secure session launcher link to frame or load the game for your player. When you call this, player balances are automatically synchronized with our transaction ledger.

JSON Body Parameters:

Integration Code Snippets

curl -X POST "https://api.win20x.com/v1/getgameurl" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "x-api-secret: YOUR_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "player123",
    "gameId": "aviator",
    "money": 1500.00,
    "platform": 1,
    "currency": "BDT",
    "home_url": "https://yourwebsite.com/lobby",
    "ip": "103.151.22.45",
    "operator_code": "skeybet"
  }'

const axios = require('axios');

axios.post('https://api.win20x.com/v1/getgameurl', {
    username: 'player123',
    gameId: 'aviator',
    money: 1500.00,
    platform: 1, // 1=Desktop, 2=Mobile
    currency: 'BDT',
    home_url: 'https://yourwebsite.com/lobby',
    ip: '103.151.22.45',
    operator_code: 'skeybet'
  }, {
    headers: {
      'x-api-key': 'YOUR_API_KEY',
      'x-api-secret': 'YOUR_API_SECRET',
      'Content-Type': 'application/json'
    }
  })
  .then(res => console.log('Launch URL:', res.data.payload.game_launch_url))
  .catch(err => console.error(err.response.data));

<?php
$ch = curl_init('https://api.win20x.com/v1/getgameurl');
$payload = json_encode([
    "username" => "player123",
    "gameId" => "aviator",
    "money" => 1500.00,
    "platform" => 1,
    "currency" => "BDT",
    "home_url" => "https://yourwebsite.com/lobby",
    "ip" => "103.151.22.45",
    "operator_code" => "skeybet"
]);

curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'x-api-key: YOUR_API_KEY',
    'x-api-secret: YOUR_API_SECRET',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$result = curl_exec($ch);
curl_close($ch);

echo $result;
?>

import requests

url = "https://api.win20x.com/v1/getgameurl"
headers = {
    "x-api-key": "YOUR_API_KEY",
    "x-api-secret": "YOUR_API_SECRET",
    "Content-Type": "application/json"
}
data = {
    "username": "player123",
    "gameId": "aviator",
    "money": 1500.00,
    "platform": 1,
    "currency": "BDT",
    "home_url": "https://yourwebsite.com/lobby",
    "ip": "103.151.22.45",
    "operator_code": "skeybet"
}

response = requests.post(url, json=data, headers=headers)
print(response.json())

Sample Response:

{
  "code": 0,
  "msg": "Success",
  "payload": {
    "game_launch_url": "https://livecasinoapi.betnex.co/game?token=8bf95935-...",
    "game_name": "Aviator",
    "provider": "SPRIBE",
    "expires_in": 60
  }
}

4. Inbound Transaction Callbacks

During game play (placing bets, wins, and bonus updates), our system will send HTTP POST webhooks back to your registered Inbound Callback Webhook URL. Your backend must listen to these events, update the player balance on your system in real-time, and return a successful JSON confirmation.

POST Request Payload:

{
  "bet_amount": 100.0000,
  "win_amount": 250.0000,
  "member_account": "p_1_user99",
  "game_uid": "75f81c56565d394503f544f3431ef370",
  "game_round": "round_unique_12345",
  "currency_code": "BDT",
  "api_key": "wjr4_api_key_xyz",
  "serial_number": "txn_unique_serial_556"
}

Required Response Body (JSON, HTTP Status 200):

{
  "success": true,
  "message": "Callback processed successfully"
}

Callback Security & Webhook Rules

To avoid security vulnerabilities (such as double payout exploits or replay attacks), your system must strictly follow these rules:

1. Validate the API Key: Check that the incoming api_key in the payload matches your own B2B API Key.
2. Player Username Masking: The incoming member_account will contain the internal masked player token we generated (e.g. p_{clientId}_{username}). Map this back to your user.
3. Strict Idempotency Check: Log the unique transaction serial_number in your database. If you receive a webhook with a serial_number that is already marked as processed in your ledger, do not deduct or credit balances again. Simply respond with success 200 OK immediately.
4. Atomic Ledger Updates: Calculate: New Balance = Current Balance - bet_amount + win_amount in a single database transaction.

Integration Code Snippets

<?php
// Inbound callback route (listen at your registered callback URL)
header('Content-Type: application/json');

$input = file_get_contents('php://input');
$data = json_decode($input, true);

// 1. Basic validation
if (!$data || !isset($data['serial_number']) || !isset($data['member_account'])) {
    echo json_encode(['success' => false, 'message' => 'Malformed payload']);
    exit;
}

$apiKey = $data['api_key'];
$memberAccount = $data['member_account'];
$betAmount = (float)$data['bet_amount'];
$winAmount = (float)$data['win_amount'];
$serialNumber = $data['serial_number'];

// 2. Validate API Key
$myApiKey = "YOUR_API_KEY"; // Set your API key here
if ($apiKey !== $myApiKey) {
    echo json_encode(['success' => false, 'message' => 'Unauthorized']);
    exit;
}

// Connect to Database
$db = new PDO('mysql:host=localhost;dbname=casino', 'db_user', 'db_pass');

try {
    $db->beginTransaction();

    // 3. Idempotency Check
    $stmt = $db->prepare("SELECT 1 FROM processed_txs WHERE serial_number = ? FOR UPDATE");
    $stmt->execute([$serialNumber]);
    if ($stmt->fetch()) {
        $db->rollBack();
        echo json_encode(['success' => true, 'message' => 'Duplicate transaction']);
        exit;
    }

    // Extract player ID from secure token (p_{clientId}_{username})
    $parts = explode('_', $memberAccount);
    $playerUsername = end($parts);

    // Lock player balance row
    $userStmt = $db->prepare("SELECT balance FROM users WHERE username = ? FOR UPDATE");
    $userStmt->execute([$playerUsername]);
    $user = $userStmt->fetch(PDO::FETCH_ASSOC);

    if (!$user) {
        $db->rollBack();
        echo json_encode(['success' => false, 'message' => 'Player not found']);
        exit;
    }

    $currentBalance = (float)$user['balance'];
    $newBalance = $currentBalance - $betAmount + $winAmount;

    if ($newBalance < 0) {
        $db->rollBack();
        echo json_encode(['success' => false, 'message' => 'Insufficient funds']);
        exit;
    }

    // Update player balance
    $updateStmt = $db->prepare("UPDATE users SET balance = ? WHERE username = ?");
    $updateStmt->execute([$newBalance, $playerUsername]);

    // Record serial number to prevent replay attacks
    $logStmt = $db->prepare("INSERT INTO processed_txs (serial_number, amount) VALUES (?, ?)");
    $logStmt->execute([$serialNumber, $winAmount - $betAmount]);

    $db->commit();
    echo json_encode(['success' => true, 'message' => 'Callback processed successfully']);

} catch (Exception $e) {
    $db->rollBack();
    echo json_encode(['success' => false, 'message' => 'Database transaction failed: ' . $e->getMessage()]);
}

const express = require('express');
const router = express.Router();
const { Pool } = require('pg');

const pool = new Pool({
  connectionString: 'postgresql://db_user:db_pass@localhost:5432/casino'
});

router.post('/callback', async (req, res) => {
  const { bet_amount, win_amount, member_account, api_key, serial_number } = req.body;

  // 1. Verify API credentials
  if (api_key !== 'YOUR_API_KEY') {
    return res.status(200).json({ success: false, message: 'Unauthorized API Key' });
  }

  const dbClient = await pool.connect();
  try {
    await dbClient.query('BEGIN');

    // 2. Idempotency Check
    const duplicateRes = await dbClient.query(
      'SELECT 1 FROM processed_txs WHERE serial_number = $1 FOR UPDATE',
      [serial_number]
    );

    if (duplicateRes.rows.length > 0) {
      await dbClient.query('ROLLBACK');
      return res.status(200).json({ success: true, message: 'Duplicate transaction skipped' });
    }

    // Extract player ID from secure token
    const playerParts = member_account.split('_');
    const playerUsername = playerParts[playerParts.length - 1];

    // Lock user row
    const userRes = await dbClient.query(
      'SELECT balance FROM users WHERE username = $1 FOR UPDATE',
      [playerUsername]
    );

    if (userRes.rows.length === 0) {
      await dbClient.query('ROLLBACK');
      return res.status(200).json({ success: false, message: 'Player not found' });
    }

    const currentBalance = parseFloat(userRes.rows[0].balance);
    const newBalance = currentBalance - parseFloat(bet_amount) + parseFloat(win_amount);

    if (newBalance < 0) {
      await dbClient.query('ROLLBACK');
      return res.status(200).json({ success: false, message: 'Insufficient balance' });
    }

    // Update user balance
    await dbClient.query(
      'UPDATE users SET balance = $1 WHERE username = $2',
      [newBalance, playerUsername]
    );

    // Record serial number
    await dbClient.query(
      'INSERT INTO processed_txs (serial_number, processed_at) VALUES ($1, NOW())',
      [serial_number]
    );

    await dbClient.query('COMMIT');
    return res.status(200).json({ success: true, message: 'Callback processed successfully' });

  } catch (err) {
    await dbClient.query('ROLLBACK');
    return res.status(200).json({ success: false, message: 'Internal transaction error: ' + err.message });
  } finally {
    dbClient.release();
  }
});

Callback Processing Logic

Every spin or game action initiates a callback sequence. A single game round can have multiple transaction events (for example, a bet callback first, followed by a win/settlement callback). Your integration must match and process these events accurately.

Callback Lifecycle & Primary Identifier

The primary unique key for any callback session is game_round. Do not treat serial_number as the round identifier. Multiple callbacks sharing the same game_round belong to the same bet round and must be aggregated rather than created as separate wagers.

Step-by-Step Processing Pipeline

Your Response to the Callback

After successfully updating the player's ledger, your handler must return a 200 OK response containing the following parameters:

Example Round with Two Callbacks

Here is a walkthrough of how player balance calculates across multiple sequential callbacks for a single round:

Error Handling & Retries

The Win20X gateway uses standard HTTP status codes to communicate request results. Your integration must properly handle these codes:

Warning: Always implement retry logic with exponential backoff delays (e.g. 1s, 2s, 4s, 8s) for all 5xx connection issues. Do not hammer failing servers with immediate requests.

Best Practices

Caching Guidelines

• Cache game catalogues: Cache results of /getallproviders and /getallgamesandprovider for up to 24 hours to reduce backend latency.
• Do not cache launcher URLs: Game session URLs expire within 60 seconds. Always request a fresh URL dynamically when a player clicks "Play".

Callback Reliability

• 5-Second Webhook Deadline: Your webhook callback endpoint must respond within 5 seconds. If a webhook hangs, our BullMQ worker will time out and mark it as a retry.
• Offload heavy processing: Perform slow database jobs (such as sending emails, alerts, or analytics logs) asynchronously. Return HTTP 200 first.

Logging & Auditing

• Log all operations: Store complete records of all outbound API requests and inbound callback payloads for at least 90 days. This is mandatory for transaction disputes.

Security Guidelines

API Key Protection

Your API Secret is highly sensitive. Keep it safe by adhering to the following regulations:

• Never store API keys/secrets in client-side code, frontend templates, or public Git repositories.
• Use secure environment variables (`.env`) or database secrets managers.

Callback Security & Validation

• Validate the api_key parameter of every incoming callback against your configured key before processing.
• Always enforce strict database-level unique constraints on the serial_number column to prevent double-payout exploits.
• Reject invalid or unauthenticated webhooks with a success: false response body and HTTP 200 status code so that the gateway retries. Do not return 4xx/5xx codes as they will not stop retries.

Transport Security & Input Sanitization

• Enforce HTTPS with TLS 1.2 or higher for all callback endpoints.
• Sanitize all webhook request inputs and use parameterized SQL queries to prevent SQL Injection vulnerabilities.

Support & Contact

Need help with your integration? Get in touch with our engineering team via the following channels: