PayStars Birleşik API · v3.0
Tek API.
StarKerak ile aynı bakiye.
Web sitesi, Telegram WebApp ve harici API aynı StarKerak bakiyesini ve karşılama motorunu kullanır. API anahtarıyla verilen siparişler düz Fragment fiyatını ek kâr marjı olmadan öder. API yanıtları JSON biçimindedir.
Kimlik doğrulama
Kontrol panelinde bir API anahtarı oluşturun. Tam anahtar yalnızca bir kez gösterilir. Sunucu ortamınızda saklayın; ön yüz JavaScript'ine veya bir Git deposuna asla koymayın.
X-API-Key: ps_your_secret_api_key Content-Type: application/json Idempotency-Key: order_20260719_0001
Limitler, doğrulama ve eşgüçlülük
- API anahtarı başına saniyede 10 istek.
- API üzerinden alıcı kontrol limiti: hesap başına dakikada 120; web sitesi/WebApp için 12.
- Satın almadan önce
/check-usernameçağırmalı ve 180 saniye geçerli birverification_tokenalmalısınız. - Her doğrulama belirteci tam olarak bir mantıksal siparişe bağlıdır; aynı eşgüçlülük anahtarıyla güvenli yeniden deneme desteklenir.
- Stars ve Premium satın alımlarında 8–128 karakterlik benzersiz bir
Idempotency-Keygönderin. - Aynı yükle aynı
Idempotency-Keyyeniden gönderildiğinde tekrar ücret alınmaz; özgün sipariş döndürülür. - Farklı bir yükle eşgüçlülük anahtarının yeniden kullanılması
409 Conflictdöndürür.
API durumu
/statuscurl https://paystars.uz/api/v1/status
USD bakiyesi ve fiyat
Hesap ve dolar bakiyesi StarKerak'tan gelir. Fiyatlar USD cinsindendir: API anahtarıyla verilen her sipariş, ek kâr marjı olmadan yalın Fragment fiyatına mal olur (mevcut tüm anahtarlar dahil). Site ve Mini Uygulama siparişleri: Fragment fiyatı + %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 fiyatı için POST /usd/quote kullanın (aşağıda): API anahtarıyla fiyat = Fragment fiyatı (ek kâr marjı yok).
Kullanıcı adı kontrolü
Bu uç nokta; adı, fotoğrafı ve Premium durumunu belirlemek için Fragment kullanır. verification_token yalnızca satın alınabilecek bir alıcı için döndürülür.
/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 veya premium değerindedir. Premium zaten etkinse premium_active: true, valid: false ve null belirteç alırsınız.
Stars siparişi
/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"
}Dolar (USD) bakiyesi ve USDT
API ödemeleri dolar bakiyesinden yapılır. Bakiye; TON, BEP20 veya TRC20 ağında USDT ile yüklenir (en az 0.1 USDT). API anahtarıyla USD fiyatı = Fragment fiyatı, ek kâr marjı yok (sente yukarı yuvarlanır). Site ve Mini Uygulamada: Fragment fiyatı + %5.
/usd/walletDolar bakiyesi, TON adresi ve kişisel not, BEP20 adresi (QR görselleriyle).
{
"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 dolar bakiyesidir (dize); usd.micros: 1 USD = 1.000.000 mikro.
/usd/invoice{"amount": 10, "chain": "ton"} veya "chain": "bsc" → 30 dakika geçerli tam tutar (ör. 10.0437). Seçilen ağdaki adrese tam olarak bu miktarda USDT gönderin (TON için not gerekmez). /usd/bsc-invoice eski takma ad olarak çalışmaya devam eder (varsayılan: bsc).
/usd/invoice/{id}/cancelBekleyen bir faturayı iptal eder (ör. tutarı değiştirmek için). İptal edilen tam tutar 24 saat boyunca başkasına verilmez ve bu süre içinde gelen ödeme yine bakiyenize işlenir.
/usd/invoice/{id}Durum: pending, paid, expired veya cancelled.
/usd/quote{"kind":"stars","username":"durov","quantity":100} veya {"kind":"premium","username":"durov","months":3} → {"usd": 1.50}.
Dolar bakiyesinden ödemek için /stars/buy veya /premium/buy yüküne, /usd/quote sonucundaki "currency": "USD" ve "max_usd": 1.50 değerlerini ekleyin. Fragment fiyatı max_usd değerini aşarsa hiçbir ücret alınmaz ve 409 price_changed döndürülür — yeni bir fiyat alın. currency atlanırsa hesabın kayıtlı para birimi tercihi (/usd/wallet içindeki pref) kullanılır — bu yüzden her zaman "currency": "USD" gönderin. Yanıttaki cost ve balance, currency alanının belirttiği para birimindedir.
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}'Siparişler
/ordersWeb sitesi, WebApp ve API üzerinden verilen son 50 siparişi döndürür.
/order/{order_id}curl https://paystars.uz/api/v1/order/1842 \
-H "X-API-Key: $PAYSTARS_API_KEY"Hatalar
| Durum | Anlam | Ne yapmalı |
|---|---|---|
| 400 | Geçersiz yük veya eşgüçlülük anahtarı | İstek biçimini kontrol edin |
| 401 | Geçersiz API anahtarı | Yeni bir anahtar oluşturun |
| 402 | Yetersiz USD bakiyesi | USDT ile yükleyin |
| 409 | Doğrulamanın süresi doldu/kullanıldı veya eşgüçlülük çakışması | Alıcıyı yeniden kontrol edin |
| 422 | Kullanıcı adı veya hizmet kullanılamıyor | Alıcıyı kontrol edin |
| 402 | insufficient_balance (USD) | Dolar bakiyesini USDT ile yükleyin |
| 409 | price_changed — USD fiyatı max_usd değerini aştı | Yeni bir /usd/quote alın |
| 429 | Hız limiti aşıldı | Retry-After sonrasında yeniden deneyin |
| 503 | Hizmet geçici olarak kullanılamıyor | Üstel geri çekilme kullanın |
{
"detail": {
"code": "insufficient_balance",
"message": "StarKerak balance is insufficient"
}
}Çalışan örnekler
Farklı programlama dillerinde
Her örnek alıcıyı kontrol eder, kısa ömürlü belirteci alır ve aynı siparişin güvenle yeniden denenebilmesi için bir eşgüçlülük anahtarı kullanır.
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)
}Tek bir istemle entegre edin
Yapay zeka istemi
Bu istemi Codex, ChatGPT veya başka bir kodlama aracısına gönderin. Köşeli parantez içindeki değerleri projenize uyacak şekilde değiştirin.
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.