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
الحدود والتحقق وعدم التكرار
- 10 طلبات في الثانية لكل مفتاح API.
- حد التحقق من المستلم عبر API: 120 في الدقيقة لكل حساب؛ و12 للموقع/WebApp.
- قبل الشراء يجب استدعاء
/check-usernameوالحصول علىverification_tokenصالح لمدة 180 ثانية. - يرتبط كل رمز تحقق بطلب منطقي واحد فقط؛ وتُدعم إعادة المحاولة بأمان باستخدام مفتاح عدم التكرار نفسه.
- أرسل
Idempotency-Keyفريدًا بطول 8–128 حرفًا مع مشتريات Stars وPremium. - إعادة إرسال
Idempotency-Keyنفسه مع البيانات نفسها لا تُخصم مرة أخرى؛ ويُعاد الطلب الأصلي. - إعادة استخدام مفتاح عدم التكرار مع بيانات مختلفة تُرجع
409 Conflict.
حالة API
/statuscurl https://paystars.uz/api/v1/status
رصيد الدولار والسعر
يأتي الحساب ورصيد الدولار من StarKerak. الأسعار بالدولار: كل طلب يُقدَّم بمفتاح 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"
}/pricesللحصول على سعر بالدولار استخدم POST /usd/quote (أدناه): مع مفتاح API، السعر = سعر Fragment (0%; الموقع: 5%).
التحقق من اسم المستخدم
تستخدم نقطة النهاية هذه Fragment لتحديد الاسم والصورة وحالة Premium. يُعاد 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 من رصيد الدولار. يُشحن بـ USDT على شبكة TON أو BEP20 أو TRC20 (الحد الأدنى 0.1 USDT). سعر الدولار عبر مفتاح API = سعر 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}.
للدفع من رصيد الدولار، أضف "currency": "USD" و"max_usd": 1.50 من /usd/quote إلى بيانات /stars/buy أو /premium/buy. إذا تجاوز سعر Fragment قيمة max_usd، لا يُخصم شيء ويُعاد 409 price_changed — احصل على تسعير جديد. إذا حُذف currency، تُستخدم تفضيلات العملة المحفوظة للحساب (pref في /usd/wallet) — لذا أرسل دائمًا "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يُرجع أحدث 50 طلبًا قُدّمت عبر الموقع وWebApp وAPI.
/order/{order_id}curl https://paystars.uz/api/v1/order/1842 \
-H "X-API-Key: $PAYSTARS_API_KEY"الأخطاء
| الحالة | المعنى | ما يجب فعله |
|---|---|---|
| 400 | بيانات غير صالحة أو مفتاح عدم تكرار غير صالح | تحقق من تنسيق الطلب |
| 401 | مفتاح API غير صالح | أنشئ مفتاحًا جديدًا |
| 402 | رصيد الدولار غير كافٍ | اشحن بـ USDT |
| 409 | انتهت صلاحية التحقق أو استُخدم، أو تعارض في عدم التكرار | أعد التحقق من المستلم |
| 422 | اسم المستخدم أو الخدمة غير متاحة | تحقق من المستلم |
| 402 | insufficient_balance (USD) | اشحن رصيد الدولار بـ USDT |
| 409 | price_changed — تجاوز سعر الدولار 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)
}التكامل بموجّه واحد
موجّه الذكاء الاصطناعي
أرسل هذا الموجّه إلى 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: 0% (Fragment price); 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.