Enterprise Sub-API v3.0 Specification

SUBOGAME API Developer API Documentation

Robust, automated, low-latency API infrastructure for Free Fire UID Top-Ups, Garena Shell vouchers, and UniPin redemptions with 99.98% uptime SLA.

API Version: 3.2.0 (Active) Published: October 2026

Format & Transport

JSON over HTTPS (REST)

All payloads consume & emit strict application/json.

Fulfillment Latency

0.85s – 2.4s Average

Sub-second automated queuing & upstream binding.

Concurrency & SLA

120+ req/min per token

Automatic retry, webhooks, and zero race condition.

Base URLs & Environments

HTTPS Only

Our API runs directly on high-performance load-balanced endpoints. Execute all API calls directly against the production base URL or your dedicated whitelabel domain.

Environment	Base Endpoint URL	Status
Production Gateway	https://api.subogame.top	Operational 99.98%
Client Reseller Console	https://api.subogame.top/portal/dashboard	Authenticated
Live API Playground	https://api.subogame.top/admin/playground	Staff & Admin

Authentication & Security Best Practices

api-key Header

All requests to protected endpoints require authentication via the api-key HTTP header. You can obtain your 64-character secret token inside your Reseller Portal.

Mandatory HTTP Headers:

api-key: your_64_character_secret_key_here

Content-Type: application/json

Accept: application/json

Server-to-Server Only

Always make API calls from your backend server (PHP, Node, Python). Never expose your API key in front-end JavaScript or client mobile apps.

Zero-Downtime Key Rotation

If your key is compromised, generate a new one instantly from the portal. Unused request balance stays 100% safe in your account.

POST

/topup

Async Fulfillment (Recommended for High Scale)

Queues the top-up transaction in our ultra-low latency background engine. The endpoint immediately returns an order confirmation status within 50ms. Once downstream fulfillment completes, our webhook engine automatically POSTs the finalized delivery report to your specified url.

Request Payload Parameters (JSON Body)

Parameter	Type	Requirement	Description
orderid	string	Required	Your unique downstream order tracking ID (e.g. `STORE-98421`). Prevents duplicate charging.
playerid	string	Required	Target Free Fire gamer Player UID (e.g. `2520777114`).
code	string	Required	Regional Server Code: `shell` (BD), `sgshell` (SG), `myshell` (MY), `indoshell` (ID), `voucher` (UniPin).
package	string	Required	Package code alias (e.g. `weekly`, `monthly`, `lite`, `115`, `240`).
qty	integer	Optional	Number of packs to send (default: 1).
url	string (URL)	Recommended	Your HTTPS webhook endpoint. Receives asynchronous order delivery report.
username / password / autocode	string	Custom Shell	Only required if utilizing your own Garena Shells account credentials.

Sample Async HTTP Request (cURL):

POST /topup

curl -X POST "https://api.subogame.top/topup" \
  -H "api-key: YOUR_64_CHAR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "orderid": "STORE-FF-98421",
    "playerid": "2520777114",
    "code": "shell",
    "package": "weekly",
    "qty": 1,
    "url": "https://yourdomain.com/api/callback"
  }'

Immediate JSON Response (Queued - HTTP 200):

200 OK (Queued)

{
  "success": true,
  "status": "processing",
  "orderid": "STORE-FF-98421",
  "playerid": "2520777114",
  "message": "Order queued successfully. Delivery in progress."
}

POST

/topup-instant

Real-Time Synchronous Execution

Executes the transaction synchronously over an open HTTP socket. The client connection holds for approximately 1.2 to 2.8 seconds while our gateway executes the upstream top-up, resolves the player's nickname, credits the diamonds, and immediately returns the final execution object.

Instant Synchronous Response (HTTP 200 Final):

200 OK (Completed in 1.48s)

{
  "status": "success",
  "orderid": "STORE-FF-98421",
  "playerid": "2520777114",
  "nickname": "TRY*AGAIN*bd",
  "diamonds_sent": 115,
  "elapsed_time": "1.48s",
  "content": {
    "batch": [
      {
        "package": "WEEKLY",
        "ok": true,
        "detail": "Delivered successfully"
      }
    ]
  }
}

POST

/topup (UniPin Voucher)

Automated PIN Redemption

Automatically redeems UniPin vouchers to target Free Fire accounts with zero human intervention. Pass the Serial and PIN in the code field separated by a space or colon (e.g. SERIAL PIN or SERIAL:PIN).

UniPin Redemption Request

curl -X POST "https://api.subogame.top/topup" \
  -H "api-key: YOUR_64_CHAR_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "orderid": "VOUCHER-ORDER-4421",
    "playerid": "2520777114",
    "code": "BDMB-T-S-01234567 1234-5678-9012-3456",
    "url": "https://yourdomain.com/api/callback"
  }'

GET

/search

Order Query & Diagnostics

Check the real-time fulfillment status, player nickname, failure reason (if any), and upstream latency of any order processed through your API key. Query by orderid or playerid.

GET /search

curl -X GET "https://api.subogame.top/search?orderid=STORE-FF-98421" \
  -H "api-key: YOUR_64_CHAR_SECRET_KEY" \
  -H "Accept: application/json"

Response (HTTP 200)

{
  "count": 1,
  "results": [
    {
      "orderid": "STORE-FF-98421",
      "status": "success",
      "playerid": "2520777114",
      "player_nickname": "TRY*AGAIN*bd",
      "package_code": "weekly",
      "diamonds_sent": "115 💎",
      "elapsed_time": "1.48s",
      "created_at": "2026-10-31 07:02:26"
    }
  ]
}

Package Catalog 1: Free Fire BD Server (`code: "shell"`)

BD Garena Shell

Package Alias	Diamonds / Description	Shell Cost	Status
lite	Weekly Lite Membership	28 Shells	Active
weekly	Weekly Membership	115 Shells	Active
monthly	Monthly Membership	575 Shells	Active
115	115 Diamonds	115 Shells	Active
240	240 Diamonds	240 Shells	Active
610	610 Diamonds	610 Shells	Active
1240	1240 Diamonds	1240 Shells	Active
2530	2530 Diamonds	2530 Shells	Active
fulllevelup	Level Up Pass (Complete Tiers)	190 Shells	Active

Package Catalog 2: SG & MY Servers (`code: "sgshell" / "myshell"`)

SG & MY Shells

Package Alias	Item Description	Shell Rate	Server Support
lite	Weekly Lite Membership	28 Shells	SG & MY
weekly	Weekly Membership	115 Shells	SG & MY
monthly	Monthly Membership	575 Shells	SG & MY
50	50 Diamonds	50 Shells	SG & MY
70	70 Diamonds	70 Shells	SG & MY
140	140 Diamonds	140 Shells	SG & MY
355	355 Diamonds	355 Shells	SG & MY
720	720 Diamonds	720 Shells	SG & MY

Production Code Samples in All Languages

Multi-Language SDK

Copy and run directly into your backend service. Each code snippet handles authentication headers, JSON payload construction, and response decoding out of the box.

terminal.sh (cURL)

curl -X POST "https://api.subogame.top/topup" \
  -H "api-key: your_secret_api_key_here" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{
    "orderid": "CLIENT-ORDER-98765",
    "playerid": "2520777114",
    "code": "shell",
    "package": "weekly",
    "qty": 1,
    "url": "https://yourwebsite.com/api/callback"
  }'

topup_client.php

<?php

$apiKey   = "your_secret_api_key_here";
$endpoint = "https://api.subogame.top/topup";

$payload = [
    "orderid"  => "ORDER-" . uniqid(),
    "playerid" => "2520777114",
    "code"     => "shell",
    "package"  => "weekly",
    "qty"      => 1,
    "url"      => "https://yourwebsite.com/api/callback"
];

$ch = curl_init($endpoint);
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($payload),
    CURLOPT_TIMEOUT        => 15,
    CURLOPT_HTTPHEADER     => [
        "api-key: " . $apiKey,
        "Content-Type: application/json",
        "Accept: application/json"
    ]
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if (curl_errno($ch)) {
    echo "cURL Error: " . curl_error($ch);
} else {
    $result = json_decode($response, true);
    echo "HTTP Status: " . $httpCode . "\n";
    print_r($result);
}
curl_close($ch);

GuzzleClient.php

<?php
require 'vendor/autoload.php';

use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;

$client = new Client([
    'base_uri' => 'https://api.subogame.top',
    'timeout'  => 10.0,
]);

try {
    $response = $client->post('/topup', [
        'headers' => [
            'api-key'      => 'your_secret_api_key_here',
            'Content-Type' => 'application/json',
            'Accept'       => 'application/json',
        ],
        'json' => [
            'orderid'  => 'GUZZLE-' . time(),
            'playerid' => '2520777114',
            'code'     => 'shell',
            'package'  => 'weekly',
            'url'      => 'https://yourwebsite.com/api/callback',
        ]
    ]);

    $data = json_decode($response->getBody()->getContents(), true);
    print_r($data);
} catch (RequestException $e) {
    echo "Error: " . $e->getMessage();
}

index.js (Axios)

import axios from 'axios';

async function executeTopup() {
    try {
        const response = await axios.post('https://api.subogame.top/topup', {
            orderid: `NODE-${Date.now()}`,
            playerid: '2520777114',
            code: 'shell',
            package: 'weekly',
            qty: 1,
            url: 'https://yourwebsite.com/api/callback'
        }, {
            headers: {
                'api-key': 'your_secret_api_key_here',
                'Content-Type': 'application/json',
                'Accept': 'application/json'
            },
            timeout: 8000
        });

        console.log('Order Successfully Dispatched:', response.data);
    } catch (error) {
        console.error('API Error:', error.response ? error.response.data : error.message);
    }
}

executeTopup();

topup_client.py

import requests
import time

url = "https://api.subogame.top/topup"
headers = {
    "api-key": "your_secret_api_key_here",
    "Content-Type": "application/json",
    "Accept": "application/json"
}
payload = {
    "orderid": f"PY-{int(time.time())}",
    "playerid": "2520777114",
    "code": "shell",
    "package": "weekly",
    "qty": 1,
    "url": "https://yourwebsite.com/api/callback"
}

response = requests.post(url, json=payload, headers=headers, timeout=10)
print(f"Status Code: {response.status_code}")
print(response.json())

Webhook Callback Specification (IPN)

Automated Delivery Push

Once our backend completes the downstream diamond reload, our system dispatches a webhook JSON POST request to your specified url. Your listener endpoint must return an HTTP 200 OK status. If your server returns an error or times out, our retry engine attempts up to 3 automatic retries with exponential backoff.

Webhook POST Payload Format:

POST to your callback url

{
  "orderid": "STORE-FF-98421",
  "status": "success",
  "playerid": "2520777114",
  "player_nickname": "TRY*AGAIN*bd",
  "diamonds_sent": 115,
  "package": "weekly",
  "elapsed_time": "1.48s",
  "content": {
    "batch": [
      {
        "package": "WEEKLY",
        "ok": true,
        "detail": "Delivered successfully"
      }
    ]
  }
}

Sample PHP Webhook Receiver (callback.php):

callback_listener.php

<?php
// Receive raw webhook JSON POST
$rawInput = file_get_contents('php://input');
$data     = json_decode($rawInput, true);

if (!$data || !isset($data['orderid'])) {
    http_response_code(400);
    exit('Invalid payload');
}

$orderId   = $data['orderid'];
$status    = $data['status']; // 'success' or 'failed'
$playerId  = $data['playerid'];
$nickname  = $data['player_nickname'] ?? '';
$diamonds  = $data['diamonds_sent'] ?? 0;

if ($status === 'success') {
    // 1. Mark order as completed in your database
    // 2. Notify your customer (SMS, Telegram, Email)
} else {
    // 1. Mark order as failed / refund customer credits
    $reason = $data['failure_reason'] ?? 'Top-up failed';
}

// Always respond with 200 OK so the gateway confirms receipt
http_response_code(200);
echo json_encode(["received" => true]);

Telegram Bot Group Binding

Real-time notification forwarding with animated custom emojis

Live Alerts

Bind your Telegram group or channel to receive real-time animated receipts whenever an order completes, fails, or when your account balance runs low.

1 Add Bot As Admin

Search for {{ \App\Models\SystemSetting::get('telegram_bot_username', 'NexaBridgeBot') }} on Telegram and add it as an Administrator to your group with "Send Messages" permission.

2 Bind Secret API Key

Type this command in the group: /bindkey YOUR_64_CHAR_KEY

Available Bot Commands

Command	Purpose	Permission
/bindkey <token>	Binds current chat to receive instant live top-up alerts	Group Admin
/unbindkey	Disconnects group from receiving webhook alerts	Group Admin
/balance	Displays remaining wallet balance and API request credits	Group Member
/status <orderid>	Directly queries live status of any downstream order	Group Member

HTTP Errors and Troubleshooting Matrix

Error Diagnostic Guide

Our gateway adheres to standard HTTP status codes. When an error occurs, the response body contains a JSON object with error description and recommended resolution.

HTTP Code	Error Name	Root Cause	Resolution Guide
200 OK	Success	Order executed or queued into downstream queue.	No action needed. Check order tracking.
400 Bad Request	Malformed JSON	Missing required parameters (`orderid`, `playerid`) or invalid JSON syntax.	Ensure `Content-Type: application/json` and all mandatory parameters are present.
401 Unauthorized	Invalid Credentials	Missing or invalid `api-key` header.	Check client dashboard and verify key matches active secret token.
402 Payment Required	Insufficient Quota	Account has 0 request credits or insufficient wallet balance for diamond reload.	Top up wallet via bKash/Nagad or buy request credits from client portal.
422 Unprocessable	Validation Error	Invalid Player UID (contains letters) or invalid package alias.	Verify Player UID exists and package alias matches reference table.
429 Rate Limit	Too Many Requests	Exceeded configured rate limit (default 120 req/min).	Implement queue throttling or contact admin for higher tier limit.
500 Server Error	Upstream Down	Garena or UniPin server temporary downtime / maintenance.	Our engine automatically retries in background. No manual resend needed.

SUBOGAME API Developer API Documentation

Base URLs & Environments

Authentication & Security Best Practices

/topup

Request Payload Parameters (JSON Body)

/topup-instant

/topup (UniPin Voucher)

/search

Package Catalog 1: Free Fire BD Server (`code: "shell"`)

Package Catalog 2: SG & MY Servers (`code: "sgshell" / "myshell"`)

Production Code Samples in All Languages

Webhook Callback Specification (IPN)

Telegram Bot Group Binding

Available Bot Commands

HTTP Errors and Troubleshooting Matrix

Need Instant Support or Custom API Integration?

Telegram Support

Phone & WhatsApp

Email Support

Dhaka, Bangladesh

SUBOGAME API Developer API Documentation

Base URLs & Environments

Authentication & Security Best Practices

/topup

Request Payload Parameters (JSON Body)

/topup-instant

/topup (UniPin Voucher)

/search

Package Catalog 1: Free Fire BD Server (code: "shell")

Package Catalog 2: SG & MY Servers (code: "sgshell" / "myshell")

Production Code Samples in All Languages

Webhook Callback Specification (IPN)

Telegram Bot Group Binding

Available Bot Commands

HTTP Errors and Troubleshooting Matrix

Need Instant Support or Custom API Integration?

Telegram Support

Phone & WhatsApp

Email Support

Dhaka, Bangladesh

Package Catalog 1: Free Fire BD Server (`code: "shell"`)

Package Catalog 2: SG & MY Servers (`code: "sgshell" / "myshell"`)