Azərbaycanca ▾
Dashboard

PayStars vahid API · v3.0

Bir API.
StarKerak ilə eyni balans.

Veb-sayt, Telegram WebApp və xarici API eyni StarKerak balansından və icra mühərrikindən istifadə edir. API açarı ilə sifarişlər adi Fragment qiymətini 0% (sayt: 5%) ödəyir. API cavabları JSON-dur.

Əsas URL: https://paystars.uz/api/v1. Bütün trafik yalnız HTTPS üzərindən göndərilməlidir.

Autentifikasiya

İdarə panelində API açarı yaradın. Tam açar yalnız bir dəfə göstərilir. Onu server mühitinizdə saxlayın; heç vaxt ön tərəf JavaScript-ə və ya Git repozitoriyasına qoymayın.

X-API-Key: ps_your_secret_api_key
Content-Type: application/json
Idempotency-Key: order_20260719_0001

Limitlər, yoxlama və idempotentlik

  • Hər API açarı üçün saniyədə 10 sorğu.
  • API vasitəsilə alıcı yoxlama limiti: hər hesab üçün dəqiqədə 120; veb-sayt/WebApp üçün 12.
  • Almazdan əvvəl /check-username çağırmalı və 180 saniyə etibarlı verification_token əldə etməlisiniz.
  • Hər yoxlama tokeni tam bir məntiqi sifarişə bağlanır; eyni idempotentlik açarı ilə təhlükəsiz təkrar cəhd dəstəklənir.
  • Stars və Premium alışları ilə unikal 8–128 simvollu Idempotency-Key göndərin.
  • Eyni Idempotency-Key eyni verilənlərlə yenidən göndərildikdə təkrar ödəniş tutulmur; ilkin sifariş qaytarılır.
  • Idempotentlik açarının fərqli verilənlərlə təkrar istifadəsi 409 Conflict qaytarır.

API statusu

GET/status
curl https://paystars.uz/api/v1/status

USD balansı və qiymət

Hesab və dollar balansı StarKerak-dan gəlir. Qiymətlər USD-dir: API açarı ilə verilən hər sifariş 0% (sayt: 5%) Fragment qiymətinə başa gəlir (bütün mövcud açarlar daxil).

GET/account
curl 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"
}
GET/prices

USD qiyməti üçün POST /usd/quote istifadə edin (aşağıda): API açarı ilə qiymət = Fragment qiyməti (0%; sayt: 5%).

İstifadəçi adı yoxlaması

Bu son nöqtə adı, şəkli və Premium statusunu müəyyən etmək üçün Fragment-dən istifadə edir. verification_token yalnız alış mümkün olan alıcı üçün qaytarılır.

POST/check-username
curl -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 və ya premium olur. Premium artıq aktivdirsə, premium_active: true, valid: false və null token alırsınız.

Stars sifarişi

POST/stars/buy
curl -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"
}

Premium sifarişi

POST/premium/buy
curl -X POST https://paystars.uz/api/v1/premium/buy \
  -H "X-API-Key: $PAYSTARS_API_KEY" \
  -H "Idempotency-Key: premium_20260719_0001" \
  -H "Content-Type: application/json" \
  -d '{"username":"telegram","months":3,"verification_token":"TOKEN_FROM_CHECK","currency":"USD","max_usd":11.99}'

months: 3, 6 və ya 12.

Dollar (USD) balansı və USDT

API ödənişləri dollar balansından edilir. O, TON, BEP20 və ya TRC20 şəbəkəsində USDT ilə artırılır (minimum 0.1 USDT). API açarı ilə USD qiyməti = Fragment qiyməti, 0% (sayt: 5%) (sentə qədər yuxarı yuvarlaqlaşdırılır).

GET/usd/wallet

Dollar balansı, TON ünvanı və şəxsi qeyd, BEP20 ünvanı (QR şəkilləri ilə).

{
  "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ıdır (sətir); usd.micros: 1 USD = 1,000,000 mikro.

POST/usd/invoice

{"amount": 10, "chain": "ton"} və ya "chain": "bsc" → 30 dəqiqə etibarlı dəqiq məbləğ (məs. 10.0437). Seçilmiş şəbəkədəki ünvana tam həmin miqdarda USDT göndərin (TON üçün qeyd lazım deyil). /usd/bsc-invoice köhnə alternativ ad kimi hələ də işləyir (standart: bsc).

POST/usd/invoice/{id}/cancel

Gözləmədə olan hesab-fakturanı ləğv edir (məsələn, məbləği dəyişmək üçün). Ləğv edilmiş dəqiq məbləğ 24 saat ərzində başqasına verilmir və həmin müddətdə gələn ödəniş yenə də balansınıza yazılır.

GET/usd/invoice/{id}

Status: pending, paid, expired və ya cancelled.

POST/usd/quote

{"kind":"stars","username":"durov","quantity":100} və ya {"kind":"premium","username":"durov","months":3} → {"usd": 1.50}.

Dollar balansından ödəmək üçün /stars/buy və ya /premium/buy gövdəsinə /usd/quote-dan "currency": "USD" və "max_usd": 1.50 əlavə edin. Fragment qiyməti max_usd-ni aşarsa, heç nə tutulmur və 409 price_changed qaytarılır — yeni qiymət sorğusu alın. currency buraxılarsa, hesabın saxlanmış valyuta seçimi (/usd/wallet içindəki pref) istifadə olunur — ona görə həmişə "currency": "USD" göndərin. Cavabdakı cost və balance currency sahəsinin göstərdiyi valyutadadır.

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}'

Sifarişlər

GET/orders

Veb-sayt, WebApp və API vasitəsilə verilmiş son 50 sifarişi qaytarır.

GET/order/{order_id}
curl https://paystars.uz/api/v1/order/1842 \
  -H "X-API-Key: $PAYSTARS_API_KEY"

Xətalar

StatusMənaNə etmək
400Yanlış gövdə və ya idempotentlik açarıSorğu formatını yoxlayın
401Yanlış API açarıYeni açar yaradın
402USD balansı kifayət deyilUSDT ilə artırın
409Yoxlamanın vaxtı bitib/istifadə olunub və ya idempotentlik ziddiyyətiAlıcını yenidən yoxlayın
422İstifadəçi adı və ya xidmət əlçatan deyilAlıcını yoxlayın
402insufficient_balance (USD)Dollar balansını USDT ilə artırın
409price_changed — USD qiyməti max_usd-ni aşdıYeni /usd/quote alın
429Sorğu limiti aşıldıRetry-After-dən sonra yenidən cəhd edin
503Xidmət müvəqqəti əlçatan deyilEksponensial gözləmə tətbiq edin
{
  "detail": {
    "code": "insufficient_balance",
    "message": "StarKerak balance is insufficient"
  }
}

İşlək nümunələr

Müxtəlif proqramlaşdırma dillərində

Hər nümunə alıcını yoxlayır, qısaömürlü tokeni alır və eyni sifarişin təhlükəsiz təkrarlanması üçün idempotentlik açarından istifadə edir.

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\"}"

Tək bir təlimatla inteqrasiya edin

AI təlimatı

Bu təlimatı Codex, ChatGPT və ya başqa kodlaşdırma agentinə göndərin. Mötərizədəki dəyərləri layihənizə uyğun dəyişin.

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.