Тоҷикӣ ▾
Dashboard

PayStars API-и ягона · v3.0

Як API.
Ҳамон тавозун, ки дар StarKerak.

Сомона, Telegram WebApp ва API-и беруна ҳама ҳамон тавозун ва муҳаррики иҷрои StarKerak-ро истифода мебаранд. Фармоишҳои калиди API нархи Fragment-ро бе изофа пардохт мекунанд. Ҷавобҳои API дар формати JSON мебошанд.

Нишонии асосӣ: https://paystars.uz/api/v1. Тамоми трафик бояд танҳо тавассути HTTPS фиристода шавад.

Тасдиқи ҳувият

Дар панели идора калиди 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 сония эътибордор гиред.
  • Ҳар токени тасдиқ ба дақиқ як фармоиши мантиқӣ баста мешавад; такрори бехатар бо ҳамон калиди идемпотентӣ дастгирӣ мешавад.
  • Бо харидҳои Stars ва Premium калиди ягонаи 8–128-аломатаи Idempotency-Key фиристед.
  • Аз нав фиристодани ҳамон Idempotency-Key бо ҳамон маълумот дубора ҳисоб намекунад; фармоиши аслӣ баргардонда мешавад.
  • Истифодаи такрории калиди идемпотентӣ бо маълумоти дигар 409 Conflict-ро бармегардонад.

Ҳолати API

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

Тавозуни долларӣ ва нарх

Ҳисоб ва тавозуни долларӣ аз StarKerak меоянд. Нархҳо бо доллар ҳастанд: ҳар фармоише, ки бо калиди API гузошта мешавад, нархи оддии Fragment-ро меарзад, бе изофа (ҳамаи калидҳои мавҷуда дохил).

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

Барои нархи долларӣ POST /usd/quote-ро (дар поён) истифода баред: бо калиди API, нарх = нархи Fragment (бе изофа).

Санҷиши номи корбар

Ин нуқтаи ниҳоӣ Fragment-ро барои муайян кардани ном, акс ва ҳолати Premium истифода мебарад. verification_token танҳо барои гирандае бармегардад, ки барояш харид мумкин аст.

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 ё premium аст. Агар Premium аллакай фаъол бошад, шумо premium_active: true, valid: false ва токени null мегиред.

Фармоиши Stars

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

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 ё 12.

Тавозуни долларӣ ва USDT

Пардохтҳои API аз тавозуни долларӣ анҷом мешаванд. Он бо USDT дар шабакаи TON, BEP20 ё TRC20 пур карда мешавад (ҳадди ақал 0.1 USDT). Нархи долларӣ тавассути калиди API = нархи Fragment, бе изофа (то сент ба боло мудаввар).

GET/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 микрос.

POST/usd/invoice

{"amount": 10, "chain": "ton"} ё "chain": "bsc" → маблағи дақиқ, ки 30 дақиқа эътибор дорад (масалан 10.0437). Маҳз ҳамин миқдор USDT-ро ба нишонӣ дар шабакаи интихобшуда фиристед (барои TON ёддошт лозим нест). /usd/bsc-invoice ҳамчун номи кӯҳна кор мекунад (пешфарз: bsc).

POST/usd/invoice/{id}/cancel

Ҳисобномаи интизориро бекор мекунад (масалан, барои тағйир додани маблағ). Маблағи дақиқи бекоршуда барои 24 соат ба каси дигар дода намешавад ва пардохте, ки дар ин муҳлат мерасад, ба ҳар ҳол ба тавозуни шумо гузаронида мешавад.

GET/usd/invoice/{id}

Ҳолат: pending, paid, expired ё cancelled.

POST/usd/quote

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

Барои пардохт аз тавозуни долларӣ, ба маълумоти /stars/buy ё /premium/buy "currency": "USD" ва "max_usd": 1.50-ро аз /usd/quote илова кунед. Агар нархи 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}'

Фармоишҳо

GET/orders

50 фармоиши охиринро, ки тавассути сомона, WebApp ва API гузошта шудаанд, бармегардонад.

GET/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Номи корбар ё хидмат дастрас нестГирандаро санҷед
402insufficient_balance (USD)Тавозуни доллариро бо USDT пур кунед
409price_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\"}"

Бо як дархост ҳамгиро кунед

Дархост барои зеҳни сунъӣ

Ин дархостро ба 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.