PayStars Unified API · v3.0
Bitta API.
StarKerak bilan bir xil balans.
Website, Telegram WebApp va tashqi API bir xil StarKerak narxlari, balans va fulfillment mexanizmidan foydalanadi. API javoblari JSON formatida.
Autentifikatsiya
Dashboard’da API kalit yarating. Kalit faqat bir marta to‘liq ko‘rsatiladi. Uni server environment’ida saqlang, frontend JavaScript yoki Git repository’ga yozmang.
X-API-Key: ps_your_secret_api_key Content-Type: application/json Idempotency-Key: order_20260719_0001
Limit, tekshiruv va idempotency
- Har bir API kalit uchun sekundiga 3 ta so‘rov.
- API orqali qabul qiluvchini tekshirish limiti: bir hisob uchun daqiqasiga 120 ta; website/WebApp uchun 12 ta.
- Xariddan oldin
/check-usernamechaqirilib, 180 soniyalikverification_tokenolinishi shart. - Har bir verification token faqat bitta mantiqiy buyurtmaga bog‘lanadi; ayni idempotency kaliti bilan xavfsiz retry mumkin.
- Stars va Premium xaridida 8–128 belgili noyob
Idempotency-Keyyuboring. - Bir xil
Idempotency-Keyva ayni payload qayta yuborilsa, yangi pul yechilmaydi; avvalgi buyurtma qaytadi. - Ayni idempotency kaliti boshqa payload bilan ishlatilsa
409 Conflictqaytadi.
API status
/statuscurl https://paystars.uz/api/v1/status
USD balans va narx
Hisob va dollar balansi StarKerak’dan olinadi. Narxlar dollarda: har bir buyurtma Fragment narxi + 5% bo‘yicha hisoblanadi.
/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 narxni olish uchun POST /usd/quote dan foydalaning (pastda): narx = Fragment narxi + 5%.
Username tekshirish
Bu endpoint Fragment orqali ism, rasm va Premium holatini aniqlaydi. verification_token faqat xarid qilish mumkin bo‘lgan qabul qiluvchi uchun qaytadi.
/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 qiymati stars yoki premium. Agar Premium mavjud bo‘lsa, premium_active: true, valid: false va token null bo‘ladi.
Stars buyurtma
/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.58}'
{
"ok": true,
"order_id": 1842,
"status": "processing",
"quantity": 100,
"cost": 1.58,
"balance": 10.92,
"currency": "USD"
}Dollar (USD) balans va USDT
API to‘lovlari dollar balansdan amalga oshadi. U TON yoki BEP20 tarmog‘idagi USDT bilan to‘ldiriladi (minimal 1 USDT). USD’da narx = Fragment narxi + 5% (sentgacha yuqoriga yaxlitlanadi).
/usd/walletDollar balans, TON manzil va shaxsiy memo, BEP20 manzil (QR rasmlari bilan).
{
"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 — dollar balans (string), usd.micros — 1 USD = 1 000 000 micros.
/usd/invoice{"amount": 10, "chain": "ton"} yoki "chain": "bsc" → 30 daqiqa amal qiladigan aniq summa (masalan 10.0437). Aynan shu summani tanlangan tarmoqdagi manzilga USDT qilib yuboring (TON uchun memo shart emas). /usd/bsc-invoice eski nom sifatida ishlaydi (standart: bsc).
/usd/invoice/{id}/cancelKutilayotgan hisobni bekor qiladi (summani o‘zgartirish uchun). Bekor qilingan aniq summa 24 soat boshqa hech kimga berilmaydi va shu vaqt ichida kelgan to‘lov baribir sizning balansingizga qo‘shiladi.
/usd/invoice/{id}Holat: pending, paid, expired yoki cancelled.
/usd/quote{"kind":"stars","username":"durov","quantity":100} yoki {"kind":"premium","username":"durov","months":3} → {"usd": 1.58}.
Xaridda dollar balansdan yechish uchun /stars/buy yoki /premium/buy payload’iga "currency": "USD" va /usd/quote dan olingan "max_usd": 1.58 qo‘shing. Fragment narxi max_usddan oshsa, pul yechilmaydi va 409 price_changed qaytadi — yangi quote oling. currency yuborilmasa, hisobning saqlangan valyuta tanlovi (/usd/wallet dagi pref) ishlatiladi — shuning uchun har doim "currency": "USD" yuboring. Javobdagi cost va balance currency maydonidagi valyutada.
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.58}'Buyurtmalar
/ordersWeb, WebApp va API orqali berilgan so‘nggi 50 ta buyurtmani qaytaradi.
/order/{order_id}curl https://paystars.uz/api/v1/order/1842 \
-H "X-API-Key: $PAYSTARS_API_KEY"Xatoliklar
| Status | Ma’nosi | Tavsiya |
|---|---|---|
| 400 | Payload yoki idempotency kalit xato | So‘rov formatini tekshiring |
| 401 | API kalit yaroqsiz | Yangi kalit yarating |
| 402 | USD balans yetarli emas | USDT bilan to‘ldiring |
| 409 | Verification eskirgan/ishlatilgan yoki idempotency konflikti | Qabul qiluvchini qayta tekshiring |
| 422 | Username yoki xizmat mavjud emas | Qabul qiluvchini tekshiring |
| 402 | insufficient_balance (USD) | Dollar balansni USDT bilan to‘ldiring |
| 409 | price_changed — USD narx max_usddan oshdi | Yangi /usd/quote oling |
| 429 | So‘rov limiti oshdi | Retry-After bo‘yicha qaytaring |
| 503 | Xizmat vaqtincha mavjud emas | Exponential backoff ishlating |
{
"detail": {
"code": "insufficient_balance",
"message": "StarKerak balance is insufficient"
}
}Ishlaydigan namunalar
Turli dasturlash tillarida
Har bir namuna qabul qiluvchini tekshiradi, qisqa muddatli tokenni oladi va ayni buyurtmani xavfsiz retry qilish uchun idempotency kalit ishlatadi.
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)
}Bir prompt bilan integratsiya
AI Prompt
Quyidagi promptni Codex, ChatGPT yoki boshqa coding agent’ga yuboring. Qavs ichidagi qiymatlarni loyihangizga moslang.
Sen senior backend va application-security muhandisisan. Menga PayStars API bilan to‘liq, production-ready integratsiya yarat.
LOYIHA TURI: [Telegram bot / web backend / mobil ilova backend]
TIL VA FRAMEWORK: [masalan: Python 3.12 + aiogram 3 + FastAPI]
LOYIHA NOMI: [nom]
PayStars base URL: https://paystars.uz/api/v1
API kalitni faqat PAYSTARS_API_KEY environment o‘zgaruvchisidan ol. Uni frontendga, logga, Git’ga yoki xatolik matniga chiqarmagin. Barcha so‘rovlar HTTPS va server tomondan bo‘lsin. Timeout, structured logging (secretsiz), input validation va testlar qo‘sh.
Quyidagi oqimni to‘liq amalga oshir:
1. GET /usd/wallet orqali USD balansni ol. Narxni lokal hardcode qilma: har xariddan oldin POST /usd/quote bilan USD narxni ol (Fragment narxi + 5%).
2. Stars yoki Premium xarididan oldin POST /check-username ga {"username":"...","kind":"stars|premium"} yubor.
3. Javobdagi valid, nickname, photo_url, premium_active va verification_token ni tekshir. Foydalanuvchiga rasm, ism, @username va Premium holatini ko‘rsatib, alohida tasdiq ol. Tasdiqsiz order yaratma.
4. verification_token 180 soniya amal qiladi. Eskirsa yoki 409 qaytsa username’ni qayta tekshir.
5. Stars uchun POST /stars/buy ga username, quantity va verification_token; Premium uchun POST /premium/buy ga username, months (3, 6 yoki 12) va verification_token yubor. Har bir xaridda "currency": "USD" va quote’dagi narxni "max_usd" sifatida yubor; 409 price_changed bo‘lsa yangi quote ol, 402 insufficient_balance bo‘lsa USD balansni USDT (TON yoki BEP20) bilan to‘ldirishni so‘ra.
6. Har mantiqiy buyurtma uchun kriptografik UUID asosidagi 8–128 belgili Idempotency-Key yarat. Network retry’da aynan o‘sha kalit va payloadni qayta ishlat; boshqa buyurtmada qayta ishlatma.
7. GET /order/{order_id} orqali holatni polling qil va GET /orders orqali tarixni ko‘rsat. processing/pending/completed/failed holatlarini to‘g‘ri boshqar.
8. API limiti har kalitga sekundiga 3 so‘rov. 429 da Retry-After’ni hurmat qil; 503 va vaqtinchalik network xatolarida jitter bilan bounded exponential backoff ishlat. 400, 401, 402, 409, 422, 429 va 503 uchun foydalanuvchiga xavfsiz, tushunarli xabar ber.
9. API javoblariga ishonib ketma: schema bo‘yicha tekshir, username’ni normalizatsiya qil, quantity/months limitini server tomonda tekshir. photo_url ni faqat ruxsat etilgan HTTPS rasm sifatida ko‘rsat. Hech qachon verification token, API key yoki to‘liq request header’larni loglama.
10. Bir foydalanuvchining parallel bosishlari, replay, duplicate order, forged callback, race condition, timeout va process restart holatlarini hisobga ol. Holatni bazada tranzaksiya bilan saqla va foydalanuvchi tasdig‘ini order bilan bog‘la.
Agar loyiha Telegram bot bo‘lsa: /start, “Stars olish”, “Premium olish”, “Balans”, “Buyurtmalar” menyularini yarat; username va miqdorni bosqichma-bosqich ol; tekshiruv natijasidan keyin inline “Tasdiqlash/Bekor qilish” tugmalarini ko‘rsat; callback ownership va TTL’ni tekshir; webhook secret yoki long-polling xavfsizligini sozla.
Natijada pseudo-code emas, ishga tushadigan to‘liq kod ber: aniq papka tuzilmasi, dependency fayli, .env.example (real secretsiz), database migration, Dockerfile, healthcheck, README, lokal ishga tushirish va deploy ko‘rsatmalari, unit/integration testlar. API client’ni alohida modul qil. Barcha narx, balans va order uchun PayStars API’ni yagona source of truth deb ol; StarKerak bazasiga to‘g‘ridan-to‘g‘ri ulanma. Yetishmayotgan biznes qiymatlarini avval qisqa ro‘yxatda so‘ra, qolgan texnik qarorlarni xavfsiz default bilan o‘zing yakunla.