PayStars متحد API · v3.0
ایک API۔
وہی بیلنس جو StarKerak کا ہے۔
ویب سائٹ، Telegram WebApp اور بیرونی API سب ایک ہی StarKerak بیلنس اور تکمیل کا انجن استعمال کرتے ہیں۔ API کلید والے آرڈر سادہ Fragment قیمت پر، 0% (ویب سائٹ: 5%) قیمت کے ادا ہوتے ہیں۔ API کے جوابات JSON ہوتے ہیں۔
تصدیق
ڈیش بورڈ میں ایک API کلید بنائیں۔ مکمل کلید صرف ایک بار دکھائی جاتی ہے۔ اسے اپنے سرور کے ماحول میں رکھیں؛ کبھی فرنٹ اینڈ JavaScript یا Git ذخیرے میں نہ ڈالیں۔
X-API-Key: ps_your_secret_api_key Content-Type: application/json Idempotency-Key: order_20260719_0001
حدود، تصدیق اور آئیڈیمپوٹنسی
- ہر API کلید پر فی سیکنڈ 10 درخواستیں۔
- API کے ذریعے وصول کنندہ کی جانچ کی حد: ہر اکاؤنٹ پر فی منٹ 120؛ ویب سائٹ/WebApp کے لیے 12۔
- خریداری سے پہلے
/check-usernameکال کرنا اور 180 سیکنڈ کے لیے درستverification_tokenحاصل کرنا ضروری ہے۔ - ہر تصدیقی ٹوکن بالکل ایک منطقی آرڈر سے منسلک ہوتا ہے؛ اسی آئیڈیمپوٹنسی کلید کے ساتھ محفوظ دوبارہ کوشش کی سہولت ہے۔
- Stars اور Premium خریداریوں کے ساتھ 8–128 حروف کی منفرد
Idempotency-Keyبھیجیں۔ - وہی
Idempotency-Keyوہی پے لوڈ کے ساتھ دوبارہ بھیجنے پر دوبارہ چارج نہیں ہوتا؛ اصل آرڈر واپس کیا جاتا ہے۔ - مختلف پے لوڈ کے ساتھ آئیڈیمپوٹنسی کلید دوبارہ استعمال کرنے پر
409 Conflictواپس آتا ہے۔
API کی حیثیت
/statuscurl https://paystars.uz/api/v1/status
USD بیلنس اور قیمت
اکاؤنٹ اور ڈالر بیلنس StarKerak سے آتے ہیں۔ قیمتیں USD میں ہیں: API کلید سے دیا گیا ہر آرڈر سادہ Fragment قیمت پر ہوتا ہے، 0% (ویب سائٹ: 5%) قیمت (تمام موجودہ کلیدیں شامل)۔ ویب سائٹ پر درست کل رقم ادائیگی سے پہلے دکھائی جاتی ہے۔
/accountcurl https://paystars.uz/api/v1/account \
-H "X-API-Key: $PAYSTARS_API_KEY"{
"ok": true,
"user": { "telegram_id": 123456789 },
"balances": { "USD": "12.50" },
"currency_pref": "USD"
}/pricesUSD قیمت کے لیے POST /usd/quote استعمال کریں (نیچے): API کلید کے ساتھ، قیمت = Fragment قیمت (0% (ویب سائٹ: 5%) قیمت)۔
صارف نام کی جانچ
یہ اینڈ پوائنٹ نام، تصویر اور Premium حیثیت معلوم کرنے کے لیے Fragment استعمال کرتا ہے۔ verification_token صرف اس وصول کنندہ کے لیے واپس ہوتا ہے جس کے لیے خریداری ممکن ہو۔
/check-usernamecurl -X POST https://paystars.uz/api/v1/check-username \ -H "X-API-Key: $PAYSTARS_API_KEY" \ -H "Content-Type: application/json" \ -d '{"username":"telegram","kind":"premium"}'
{
"valid": true,
"username": "telegram",
"nickname": "Telegram User",
"photo_url": "https://cdn4.telesco.pe/...",
"premium_active": false,
"verification_token": "...",
"verification_expires_in": 180
}kind stars یا premium ہوتا ہے۔ اگر Premium پہلے سے فعال ہو تو آپ کو premium_active: true، valid: false اور null ٹوکن ملتا ہے۔
Stars آرڈر
/stars/buycurl -X POST https://paystars.uz/api/v1/stars/buy \ -H "X-API-Key: $PAYSTARS_API_KEY" \ -H "Idempotency-Key: order_20260719_0001" \ -H "Content-Type: application/json" \ -d '{"username":"telegram","quantity":100,"verification_token":"TOKEN_FROM_CHECK","currency":"USD","max_usd":1.50}'
{
"ok": true,
"order_id": 1842,
"status": "processing",
"quantity": 100,
"cost": 1.50,
"balance": 10.92,
"currency": "USD"
}ڈالر (USD) بیلنس اور USDT
API ادائیگیاں ڈالر بیلنس سے کی جاتی ہیں۔ اسے TON، BEP20 یا TRC20 نیٹ ورک پر USDT سے بھرا جاتا ہے (کم از کم 0.1 USDT)۔ API کلید سے USD قیمت = Fragment قیمت، 0% (ویب سائٹ: 5%) قیمت (سینٹ تک اوپر گول)۔
/usd/walletڈالر بیلنس، TON پتہ اور ذاتی میمو، BEP20 پتہ (QR تصاویر کے ساتھ)۔
{
"ok": true,
"usd": { "balance": "12.50", "micros": 12500000 },
"min_deposit": "1.00",
"ton": { "address": "UQ...", "memo": "...", "enabled": true, "ttl_min": 30 },
"bsc": { "address": "0x...", "contract": "0x55d398326f99059fF775485246999027B3197955", "enabled": true, "ttl_min": 30 }
}usd.balance ڈالر بیلنس ہے (سٹرنگ)؛ usd.micros: 1 USD = 1,000,000 مائیکرو۔
/usd/invoice{"amount": 10, "chain": "ton"} یا "chain": "bsc" → 30 منٹ کے لیے درست بالکل درست رقم (مثلاً 10.0437)۔ منتخب نیٹ ورک کے پتے پر USDT کی بالکل وہی رقم بھیجیں (TON کے لیے میمو کی ضرورت نہیں)۔ /usd/bsc-invoice اب بھی پرانے متبادل نام کے طور پر کام کرتا ہے (طے شدہ: bsc)۔
/usd/invoice/{id}/cancelزیر التوا انوائس منسوخ کرتا ہے (مثلاً رقم بدلنے کے لیے)۔ منسوخ شدہ بالکل درست رقم 24 گھنٹے تک کسی اور کو نہیں دی جاتی، اور اس وقفے میں آنے والی ادائیگی پھر بھی آپ کے بیلنس میں جمع ہوتی ہے۔
/usd/invoice/{id}حیثیت: pending، paid، expired یا cancelled۔
/usd/quote{"kind":"stars","username":"durov","quantity":100} یا {"kind":"premium","username":"durov","months":3} → {"usd": 1.50}۔
ڈالر بیلنس سے ادائیگی کے لیے /usd/quote سے "currency": "USD" اور "max_usd": 1.50 کو /stars/buy یا /premium/buy کے پے لوڈ میں شامل کریں۔ اگر Fragment قیمت max_usd سے زیادہ ہو تو کچھ نہیں کاٹا جاتا اور 409 price_changed واپس آتا ہے — نیا کوٹ حاصل کریں۔ اگر currency چھوڑ دیا جائے تو اکاؤنٹ کی محفوظ کرنسی ترجیح (/usd/wallet میں pref) استعمال ہوتی ہے — اس لیے ہمیشہ "currency": "USD" بھیجیں۔ جواب میں cost اور balance اسی کرنسی میں ہوتے ہیں جو currency فیلڈ بتاتی ہے۔
curl -X POST https://paystars.uz/api/v1/stars/buy \
-H "X-API-Key: $PAYSTARS_API_KEY" -H "Idempotency-Key: stars_8f2c1a9b" \
-H "Content-Type: application/json" \
-d '{"username":"durov","quantity":100,"verification_token":"...","currency":"USD","max_usd":1.50}'آرڈرز
/ordersویب سائٹ، WebApp اور API کے ذریعے دیے گئے تازہ ترین 50 آرڈرز واپس کرتا ہے۔
/order/{order_id}curl https://paystars.uz/api/v1/order/1842 \
-H "X-API-Key: $PAYSTARS_API_KEY"خرابیاں
| حیثیت | مطلب | کیا کریں |
|---|---|---|
| 400 | غلط پے لوڈ یا آئیڈیمپوٹنسی کلید | درخواست کی شکل چیک کریں |
| 401 | غلط API کلید | نئی کلید بنائیں |
| 402 | ناکافی USD بیلنس | USDT سے بھریں |
| 409 | تصدیق ختم/استعمال شدہ یا آئیڈیمپوٹنسی تصادم | وصول کنندہ دوبارہ چیک کریں |
| 422 | صارف نام یا سروس دستیاب نہیں | وصول کنندہ چیک کریں |
| 402 | insufficient_balance (USD) | ڈالر بیلنس USDT سے بھریں |
| 409 | price_changed — USD قیمت max_usd سے زیادہ ہو گئی | نیا /usd/quote حاصل کریں |
| 429 | درخواست کی حد سے تجاوز | Retry-After کے بعد دوبارہ کوشش کریں |
| 503 | سروس عارضی طور پر دستیاب نہیں | وقفہ بڑھا کر دوبارہ کوشش کریں |
{
"detail": {
"code": "insufficient_balance",
"message": "StarKerak balance is insufficient"
}
}کام کرنے والی مثالیں
مختلف پروگرامنگ زبانوں میں
ہر مثال وصول کنندہ چیک کرتی ہے، قلیل مدتی ٹوکن حاصل کرتی ہے اور آئیڈیمپوٹنسی کلید استعمال کرتی ہے تاکہ وہی آرڈر محفوظ طریقے سے دوبارہ کوشش کیا جا سکے۔
API="https://paystars.uz/api/v1"
ORDER_KEY="stars_$(uuidgen)"
VERIFY=$(curl --fail-with-body -sS -X POST "$API/check-username" \
-H "X-API-Key: $PAYSTARS_API_KEY" \
-H "Content-Type: application/json" \
-d '{"username":"telegram","kind":"stars"}')
TOKEN=$(printf '%s' "$VERIFY" | jq -r '.verification_token')
curl --fail-with-body -sS -X POST "$API/stars/buy" \
-H "X-API-Key: $PAYSTARS_API_KEY" \
-H "Idempotency-Key: $ORDER_KEY" \
-H "Content-Type: application/json" \
-d "{\"username\":\"telegram\",\"quantity\":100,\"verification_token\":\"$TOKEN\",\"currency\":\"USD\"}"import { randomUUID } from 'node:crypto';
const base = 'https://paystars.uz/api/v1';
const headers = { 'X-API-Key': process.env.PAYSTARS_API_KEY, 'Content-Type': 'application/json' };
const verify = await fetch(`${base}/check-username`, {
method: 'POST', headers, body: JSON.stringify({ username: 'telegram', kind: 'stars' })
}).then(async r => { if (!r.ok) throw new Error(await r.text()); return r.json(); });
const order = await fetch(`${base}/stars/buy`, {
method: 'POST', headers: { ...headers, 'Idempotency-Key': `stars_${randomUUID()}` },
body: JSON.stringify({ username: verify.username, quantity: 100, verification_token: verify.verification_token, currency: 'USD' })
}).then(async r => { if (!r.ok) throw new Error(await r.text()); return r.json(); });
console.log(order.order_id, order.status);import os, uuid, requests
base = "https://paystars.uz/api/v1"
headers = {"X-API-Key": os.environ["PAYSTARS_API_KEY"]}
verify = requests.post(f"{base}/check-username", headers=headers,
json={"username": "telegram", "kind": "premium"}, timeout=15)
verify.raise_for_status()
recipient = verify.json()
order = requests.post(f"{base}/premium/buy", headers={
**headers, "Idempotency-Key": f"premium_{uuid.uuid4()}"
}, json={"username": recipient["username"], "months": 3,
"verification_token": recipient["verification_token"], "currency": "USD"}, timeout=20)
order.raise_for_status()
print(order.json())<?php
$base = 'https://paystars.uz/api/v1';
$key = getenv('PAYSTARS_API_KEY');
function postJson($url, $headers, $body) {
$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => json_encode($body), CURLOPT_TIMEOUT => 20]);
$raw = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch);
if ($status < 200 || $status >= 300) throw new RuntimeException($raw);
return json_decode($raw, true, flags: JSON_THROW_ON_ERROR);
}
$common = ["X-API-Key: $key", 'Content-Type: application/json'];
$user = postJson("$base/check-username", $common, ['username' => 'telegram', 'kind' => 'stars']);
$order = postJson("$base/stars/buy", [...$common, 'Idempotency-Key: stars_'.bin2hex(random_bytes(16))],
['username' => $user['username'], 'quantity' => 100, 'verification_token' => $user['verification_token'], 'currency' => 'USD']);
print_r($order);package main
import ("bytes"; "encoding/json"; "fmt"; "io"; "net/http"; "os"; "github.com/google/uuid")
func post(path string, body any, idempotency string, out any) error {
data, _ := json.Marshal(body)
req, _ := http.NewRequest("POST", "https://paystars.uz/api/v1"+path, bytes.NewReader(data))
req.Header.Set("X-API-Key", os.Getenv("PAYSTARS_API_KEY")); req.Header.Set("Content-Type", "application/json")
if idempotency != "" { req.Header.Set("Idempotency-Key", idempotency) }
res, err := http.DefaultClient.Do(req); if err != nil { return err }; defer res.Body.Close()
if res.StatusCode >= 300 { raw, _ := io.ReadAll(res.Body); return fmt.Errorf("API %d: %s", res.StatusCode, raw) }
return json.NewDecoder(res.Body).Decode(out)
}
func main() {
var user struct { Username string `json:"username"`; VerificationToken string `json:"verification_token"` }
if err := post("/check-username", map[string]any{"username":"telegram", "kind":"stars"}, "", &user); err != nil { panic(err) }
var order map[string]any
if err := post("/stars/buy", map[string]any{"username":user.Username, "quantity":100,
"verification_token":user.VerificationToken, "currency":"USD"}, "stars_"+uuid.NewString(), &order); err != nil { panic(err) }
fmt.Println(order)
}ایک ہی پرامپٹ سے مربوط کریں
AI پرامپٹ
یہ پرامپٹ Codex، ChatGPT یا کسی اور کوڈنگ ایجنٹ کو بھیجیں۔ اپنے منصوبے کے مطابق بریکٹ میں دی گئی قدریں بدلیں۔
You are a senior backend and application-security engineer. Build me a complete, production-ready integration with the PayStars API.
PROJECT TYPE: [Telegram bot / web backend / mobile app backend]
LANGUAGE AND FRAMEWORK: [e.g. Python 3.12 + aiogram 3 + FastAPI]
PROJECT NAME: [name]
PayStars base URL: https://paystars.uz/api/v1
Read the API key only from the PAYSTARS_API_KEY environment variable. Never expose it to the frontend, logs, Git or error messages. All requests must be HTTPS and server-side. Add timeouts, structured logging (without secrets), input validation and tests.
Implement the following flow completely:
1. Get the USD balance via GET /usd/wallet. Do not hardcode prices: before every purchase get the USD price via POST /usd/quote (with an API key: plain Fragment price, 0% (website: 5%)).
2. Before a Stars or Premium purchase, send {"username":"...","kind":"stars|premium"} to POST /check-username.
3. Check valid, nickname, photo_url, premium_active and verification_token in the response. Show the user the photo, name, @username and Premium status and get explicit confirmation. Do not create an order without confirmation.
4. verification_token is valid for 180 seconds. If it expires or a 409 is returned, re-check the username.
5. For Stars send username, quantity and verification_token to POST /stars/buy; for Premium send username, months (3, 6 or 12) and verification_token to POST /premium/buy. In every purchase send "currency": "USD" and the quoted price as "max_usd"; on 409 price_changed fetch a new quote, on 402 insufficient_balance ask the user to top up the USD balance with USDT (TON, BEP20 or TRC20).
6. For each logical order generate an 8–128 character Idempotency-Key based on a cryptographic UUID. On network retries reuse exactly the same key and payload; never reuse it for another order.
7. Poll status via GET /order/{order_id} and show history via GET /orders. Handle processing/pending/completed/failed states correctly.
8. The API limit is 10 requests per second per key. On 429 honour Retry-After; on 503 and transient network errors use bounded exponential backoff with jitter. Give the user a safe, clear message for 400, 401, 402, 409, 422, 429 and 503.
9. Do not trust API responses blindly: validate against a schema, normalise usernames, enforce quantity/months limits server-side. Display photo_url only as an allowed HTTPS image. Never log the verification token, API key or full request headers.
10. Handle concurrent clicks by the same user, replay, duplicate orders, forged callbacks, race conditions, timeouts and process restarts. Persist state in the database with transactions and bind the user's confirmation to the order.
If the project is a Telegram bot: create /start, "Buy Stars", "Buy Premium", "Balance", "Orders" menus; collect the username and amount step by step; after the check show inline "Confirm/Cancel" buttons; verify callback ownership and TTL; secure the webhook secret or long-polling setup.
Deliver real, runnable code, not pseudo-code: exact folder structure, dependency file, .env.example (no real secrets), database migrations, Dockerfile, healthcheck, README, local run and deploy instructions, unit/integration tests. Put the API client in a separate module. Treat the PayStars API as the single source of truth for all prices, balances and orders; never connect to the StarKerak database directly. First ask for any missing business values as a short list, and make the remaining technical decisions yourself with safe defaults.