Developer Documentation

ZankethStore
Reseller API

Deliver game top-ups instantly through our secure fulfilment platform. One POST request — we handle queuing, balance checks, dispatch, and confirmation. Built for reseller integrations.

Base URLhttps://zankethstore.com/tg/api.php

📡Overview

The ZankethStore Reseller API lets authorised developers trigger game top-ups via a single HTTP POST. You send the player ID and item code — the API validates your key, checks balance, serialises through the queue, dispatches to the fulfilment system, waits for confirmation, deducts your balance, and returns structured JSON.

💡

Every response includes ok (boolean), status (machine-readable), message (human-readable), and data (payload). Always check ok first.

Request lifecycle

01POST
request

→

02Auth &
balance

→

03Queue
lock

→

04Dispatch
command

→

05Poll
reply

→

06Deduct
balance

→

07JSON
response

⚠️

Requests can take up to 90 seconds (queue wait + fulfilment). Always set your HTTP client timeout to at least 120 seconds.

🔑Authentication

Include your API key on every request as a POST field or HTTP header.

Method	Where	Example
POST field	Request body	api_key=your-secret-key
HTTP Header	Request headers	X-API-Key: your-secret-key

ℹ️

API keys are stored as SHA-256 hashes — the raw key is never stored. If lost it cannot be recovered; request a new one from the admin.

Key properties

Property	Description
allowed_domains	Comma-separated whitelist. Requests from unlisted origins → 403.
expires_at	Expiry datetime. `null` = never expires.
rate_limit	Max calls per 60-second window. `0` = unlimited.
balance	Shell balance. Auto-deducted on each successful top-up.
is_active	Admin can disable instantly. Disabled → 403.

⚙️Queue System

Only one top-up dispatches at a time. This prevents fulfilment responses from being mixed up when multiple requests arrive simultaneously.

── No other requests running ────────────────────────────────── Row inserted → proceed immediately → dispatch → poll → done ── Another request is already processing ────────────────────── Row inserted → detects other row → wait (check every 2s) Other finishes at 30s → proceed immediately at 30s ── Other request is stuck ≥ 60s (crash / timeout) ───────────── Stale row → mark as timeout → proceed immediately

ℹ️

Worst-case queue wait is 60 seconds (for a stale/crashed request). Normal wait = however long the active request takes — often 5–30 seconds. Set HTTP timeout to 120s minimum.

🚀Top-Up Endpoint

POST/api.php

Validates balance, queues the request, dispatches to fulfilment, waits for confirmation, deducts balance, and returns the result.

Request parameters

Parameter	Type	Required	Description
api_key	string	REQUIRED	Reseller API key. Or use `X-API-Key` header.
player_id	string	REQUIRED	In-game player ID to top up.
item_code	string	REQUIRED	Item to deliver (lowercase). See Item Codes.
quantity	integer	OPTIONAL	Units. Default: `1`. Max: `99`.

Success 200

json

{
  "ok": true, "status": "success",
  "message": "✅ Top-up delivered successfully.",
  "data": {
    "queue_id": 1042, "product": "Weekly Pass",
    "shell_cost": 86, "balance_before": 5000, "balance_after": 4914,
    "shells_deducted": "86 SHELLS", "new_balance": "4914.00 SHELLS"
  }
}

Insufficient balance 402

json

{
  "ok": false, "status": "low_balance",
  "message": "Insufficient balance. Required: 86 SHELLS, Available: 40 SHELLS.",
  "data": { "queue_id": 1043, "required_shells": 86, "available_shells": 40 }
}

Failed / timeout 502

json

{
  "ok": false, "status": "failed",
  "message": "⚠️ Top-up failed or timed out.",
  "data": { "queue_id": 1044, "debug_msgs": ["..."] }
}

📦Products Endpoint

GET/api.php?products

Returns the live product catalogue. No authentication required. Fetch this at startup to keep pricing in sync.

json

{
  "ok": true,
  "products": [
    { "item_code": "25",     "name": "25 Shells Pack",  "shell_cost": "13.00" },
    { "item_code": "weekly", "name": "Weekly Pass",     "shell_cost": "86.00" }
  ]
}

🩺Health Check

GET/api.php?test

Returns server health — PHP version, DB connectivity, table existence, reseller count. No auth required. Use to diagnose integration issues before going live.

🔍Player Verification

GET/api.php?verify&api_key=KEY&uid=UID&region=REGION

Looks up a player's username and profile before placing a top-up order. Requires a valid API key — included free with all reseller accounts. The upstream verification service URL and credentials are never exposed.

Parameters

Parameter	Type	Required	Description
api_key	string	REQUIRED	Your reseller API key.
uid	string	REQUIRED	In-game player UID to look up.
region	string	OPTIONAL	Server region code (e.g. `SG`). Default: `SG`.

Success 200

json

{
  "ok": true,
  "status": "found",
  "data": {
    "username": "NLㅤxPsʏᴄʜᴏ☂",
    "uid":      "123456789",
    "region":   "SG"
  }
}

💡

Always verify the player UID before placing a top-up order. A wrong UID wastes shells with no recourse. Call this endpoint from your checkout page to confirm the player name before payment.

cURL example

bash

curl "https://zankethstore.com/tg/api.php?verify&api_key=your-key&uid=123456789®ion=SG"

PHP example

php

$res = json_decode(file_get_contents(
    'https://zankethstore.com/tg/api.php?verify'
    .'&api_key=your-key'
    .'&uid=' . urlencode($playerId)
    .'®ion=SG'
), true);

if ($res['ok']) {
    echo "Player: " . $res['data']['username'];
} else {
    echo "Not found: " . $res['message'];
}

🎮Item Codes

Pass item_code exactly as shown (lowercase). Total shell cost = shell_cost × quantity.

Shell packs

item_code	Name	Shell Cost / unit
25	25 Shells Pack	13 SHELLS
100	100 Shells Pack	50 SHELLS
310	310 Shells Pack	152 SHELLS
520	520 Shells Pack	254 SHELLS
1060	1,060 Shells Pack	500 SHELLS
2180	2,180 Shells Pack	1,010 SHELLS
5600	5,600 Shells Pack	2,500 SHELLS
11500	11,500 Shells Pack	5,150 SHELLS

Passes & subscriptions

item_code	Name	Shell Cost / unit
lite	Lite Pass	18 SHELLS
weekly	Weekly Pass	86 SHELLS
monthly	Monthly Pass	430 SHELLS

Evo passes

item_code	Name	Shell Cost / unit
evo3	Evo 3-Day Pass	30 SHELLS
evo7	Evo 7-Day Pass	45 SHELLS
evo30	Evo 30-Day Pass	135 SHELLS

💡

Always call GET /api.php?products at startup to get live pricing. Admin can update prices at any time.

⚡Error Codes

All errors return JSON with "ok": false. Use the status field for programmatic handling.

HTTP

status

Cause & fix

400

missing_player
missing_item

Required POST field missing.

401

missing_key
invalid_key

Key absent or unknown. Visit ?checkkey=YOUR_KEY to diagnose.

403

disabled
key_expired
domain_blocked

Account disabled, key expired, or origin not whitelisted.

402

low_balance

Shell balance too low. Response includes required_shells and available_shells.

429

rate_limited

Too many requests in 60s. Slow down or ask admin to raise limit.

500

processing_error
db_error

Server error. Contact admin with your queue_id.

502

failed

Fulfilment failed or timed out. Check debug_msgs and retry.

🛡️Security

Key Hashing

Raw keys never stored. Only SHA-256 hashes in DB.

Domain Whitelist

Each key locked to approved domains. Unknown origins → 403.

Balance Guard

Shell balance checked before dispatch. Orders that would overdraft → 402.

Queue Lock

Only one fulfilment runs at a time. Prevents mixed responses.

Key Expiry

Every key has an expiry date. Expired → 403. Renew via admin panel.

Audit Log

Every call logged to api_call_log with IP, domain, status, timestamp.

🚨

Never expose your API key in client-side JavaScript or public repos. All calls must come from your server backend, not from browsers.

⏱Rate Limits

Sliding 60-second window per API key. Exceeding the limit → 429.

Plan	Limit	Use case
Standard	30 / min	Moderate traffic
High-volume	60 / min	Busy storefronts
Unlimited	0 (none)	Trusted internal systems

⚠️

Do not send concurrent requests from the same key. Each request waits in the queue — concurrent calls all count against the rate limit while waiting.

🐘PHP

php

<?php
$ch = curl_init();
curl_setopt_array($ch, [
    CURLOPT_URL            => 'https://zankethstore.com/tg/api.php',
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_POST           => true,
    CURLOPT_TIMEOUT        => 120,
    CURLOPT_POSTFIELDS     => http_build_query([
        'api_key'   => 'your-reseller-api-key',
        'player_id' => '123456789',
        'item_code' => 'weekly',
        'quantity'  => 1,
    ]),
]);
$res = json_decode(curl_exec($ch), true);
curl_close($ch);

if ($res['ok']) {
    echo "✅ Cost: " . $res['data']['shell_cost'] . " | Balance: " . $res['data']['balance_after'];
} elseif ($res['status'] === 'low_balance') {
    echo "❌ Need: ".$res['data']['required_shells']." | Have: ".$res['data']['available_shells'];
} else {
    echo "❌ " . $res['message'];
}

🟨JavaScript (Node.js)

javascript

const axios = require('axios');

async function topUp(playerId, itemCode, qty = 1) {
  const { data } = await axios.post(
    'https://zankethstore.com/tg/api.php',
    new URLSearchParams({ api_key: 'your-key', player_id: playerId, item_code: itemCode, quantity: qty }).toString(),
    { headers: { 'Content-Type': 'application/x-www-form-urlencoded' }, timeout: 120000 }
  );
  if (data.ok) console.log(`✅ Cost: ${data.data.shell_cost} | Balance: ${data.data.balance_after}`);
  else if (data.status === 'low_balance') console.error(`❌ Need ${data.data.required_shells}, have ${data.data.available_shells}`);
  else console.error(`❌ ${data.message}`);
  return data;
}

🐍Python

python

import requests

def top_up(player_id, item_code, quantity=1):
    data = requests.post(
        'https://zankethstore.com/tg/api.php',
        data={'api_key': 'your-key', 'player_id': player_id,
              'item_code': item_code, 'quantity': quantity},
        timeout=120
    ).json()
    if data['ok']:
        print(f"✅ Cost: {data['data']['shell_cost']} | Balance: {data['data']['balance_after']}")
    elif data['status'] == 'low_balance':
        print(f"❌ Need {data['data']['required_shells']}, have {data['data']['available_shells']}")
    else:
        print(f"❌ {data['message']}")
    return data

🖥cURL

bash

# Top-up
curl -X POST https://zankethstore.com/tg/api.php \
  --max-time 120 \
  -d "api_key=your-key" \
  -d "player_id=123456789" \
  -d "item_code=weekly" \
  -d "quantity=1"

# Live product list
curl https://zankethstore.com/tg/api.php?products

# Health check
curl https://zankethstore.com/tg/api.php?test

# Diagnose key
curl https://zankethstore.com/tg/api.php?checkkey=your-raw-key

⚙️Key Management

Create and manage keys from the Admin Panel at /admin.php or via the CLI script.

bash

# List resellers
php reseller_admin.php list

# Create (prints key ONCE — save immediately)
php reseller_admin.php add "Shop Name" "shop.com" 365 60

# Disable / enable
php reseller_admin.php revoke 3
php reseller_admin.php enable 3

# History & stats
php reseller_admin.php history 3
php reseller_admin.php stats

⚠️

The raw API key is shown once only at creation. Only its SHA-256 hash is stored. Copy it immediately.

🗄️Database

Run api_schema.sql once to create all tables. Safe to re-run.

resellers

Column	Type	Notes
api_key	VARCHAR(64)	SHA-256 hash of raw key
balance	DECIMAL(10,2)	Auto-deducted on success. Top up via admin.
allowed_domains	TEXT	Comma-separated whitelist
rate_limit	SMALLINT	Calls/min. 0 = unlimited

products

Column	Type	Notes
item_code	VARCHAR(60)	Unique, lowercase. Matches API `item_code`
shell_cost	DECIMAL(10,2)	Cost per unit checked against reseller balance
is_active	TINYINT(1)	Inactive items → `missing_item` error

api_queue

Column	Notes
id	Returned as `queue_id` in all responses
reseller_id	NULL for internal orders (manual/wallet/instant)
status	pending → processing → success \| failed \| timeout
origin_domain	`manual` / `instant` / `wallet` / reseller domain

ZankethStoreReseller API

📡Overview

Request lifecycle

🔑Authentication

Key properties

⚙️Queue System

🚀Top-Up Endpoint

Request parameters

Success 200

Insufficient balance 402

Failed / timeout 502

📦Products Endpoint

🩺Health Check

🔍Player Verification

Parameters

Success 200

cURL example

PHP example

🎮Item Codes

Shell packs

Passes & subscriptions

Evo passes

⚡Error Codes

🛡️Security

Key Hashing

Domain Whitelist

Balance Guard

Queue Lock

Key Expiry

Audit Log

⏱Rate Limits

🐘PHP

🟨JavaScript (Node.js)

🐍Python

🖥cURL

⚙️Key Management

🗄️Database

resellers

products

api_queue

ZankethStore
Reseller API