አማርኛ ▾
Dashboard

PayStars የተዋሃደ API · v3.0

አንድ API።
ከ StarKerak ጋር አንድ አይነት ቀሪ ሂሳብ።

ድረ-ገጹ፣ Telegram WebApp እና ውጫዊ API ሁሉም ተመሳሳይ የ StarKerak ቀሪ ሂሳብ እና የማሟያ ሞተር ይጠቀማሉ። በ API ቁልፍ የሚደረጉ ትዕዛዞች ቀላል የ Fragment ዋጋን 0% (ድረ-ገጽ: 5%) ይከፍላሉ። የ API ምላሾች JSON ናቸው።

መሠረታዊ URL፦ 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

ገደቦች፣ ማረጋገጫ እና ድጋሚ-ጥያቄ ደህንነት

  • በአንድ API ቁልፍ በሰከንድ 10 ጥያቄዎች።
  • በ API የተቀባይ ማረጋገጫ ገደብ፦ በደቂቃ በመለያ 120፤ ለድረ-ገጽ/WebApp 12።
  • ከመግዛትዎ በፊት /check-username መጥራት እና ለ 180 ሰከንድ የሚሰራ verification_token ማግኘት አለብዎት።
  • እያንዳንዱ የማረጋገጫ ቶከን በትክክል ከአንድ ምክንያታዊ ትዕዛዝ ጋር የተሳሰረ ነው፤ በተመሳሳይ የኢዴምፖተንሲ ቁልፍ በደህና እንደገና መሞከር ይደገፋል።
  • ለ Stars እና Premium ግዢዎች ልዩ የሆነ ከ 8–128 ቁምፊ ያለው Idempotency-Key ይላኩ።
  • ተመሳሳይ Idempotency-Keyን ከተመሳሳይ ጭነት ጋር እንደገና መላክ እንደገና አይከፍልም፤ የመጀመሪያው ትዕዛዝ ይመለሳል።
  • የኢዴምፖተንሲ ቁልፍን ከተለየ ጭነት ጋር እንደገና መጠቀም 409 Conflict ይመልሳል።

የ API ሁኔታ

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

የ USD ቀሪ ሂሳብ እና ዋጋ

መለያው እና የዶላር ቀሪ ሂሳብ ከ StarKerak ይመጣሉ። ዋጋዎች በ USD ናቸው፦ በ API ቁልፍ የሚቀመጥ እያንዳንዱ ትዕዛዝ ቀላል የ Fragment ዋጋ ነው፣ 0% (ድረ-ገጽ: 5%) (ሁሉም ነባር ቁልፎችን ጨምሮ)። በጣቢያው ትክክለኛው ድምር ከመክፈልዎ በፊት ይታያል።

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 ዋጋ POST /usd/quote ይጠቀሙ (ከታች)፦ በ API ቁልፍ፣ ዋጋ = የ Fragment ዋጋ (0%; ድረ-ገጽ: 5%)።

የተጠቃሚ ስም ማረጋገጫ

ይህ መጨረሻ ነጥብ ስም፣ ፎቶ እና የ Premium ሁኔታ ለመፍታት Fragment ይጠቀማል። 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።

የዶላር (USD) ቀሪ ሂሳብ እና USDT

የ API ክፍያዎች ከየዶላር ቀሪ ሂሳብ ይከናወናሉ። በ TON፣ BEP20 ወይም TRC20 አውታረ መረብ ላይ በ USDT ይሞላል (ዝቅተኛ 0.1 USDT)። በ API ቁልፍ የ USD ዋጋ = የ Fragment ዋጋ፣ 0% (ድረ-ገጽ: 5%) (እስከ ሳንቲም ወደ ላይ የተጠጋጋ)። በጣቢያው ትክክለኛው ድምር ከመክፈልዎ በፊት ይታያል።

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

ከዶላር ቀሪ ሂሳብ ለመክፈል፣ "currency": "USD" እና ከ/usd/quote የተገኘውን "max_usd": 1.50 ወደ /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}'

ትዕዛዞች

GET/orders

በድረ-ገጽ፣ WebApp እና API የተቀመጡ የቅርብ 50 ትዕዛዞችን ይመልሳል።

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

ስህተቶች

ሁኔታትርጉምምን ማድረግ እንዳለብዎ
400ልክ ያልሆነ ጭነት ወይም የኢዴምፖተንሲ ቁልፍየጥያቄውን ቅርጸት ያረጋግጡ
401ልክ ያልሆነ የ API ቁልፍአዲስ ቁልፍ ይፍጠሩ
402በቂ ያልሆነ የ USD ቀሪ ሂሳብበ USDT ይሙሉ
409ማረጋገጫ ጊዜው አልፏል/ጥቅም ላይ ውሏል ወይም የኢዴምፖተንሲ ግጭትተቀባዩን እንደገና ያረጋግጡ
422የተጠቃሚ ስም ወይም አገልግሎት አይገኝምተቀባዩን ያረጋግጡ
402insufficient_balance (USD)የዶላር ቀሪ ሂሳቡን በ USDT ይሙሉ
409price_changed — የ USD ዋጋ 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\"}"

በአንድ መመሪያ ያዋህዱ

የ AI መመሪያ

ይህን መመሪያ ወደ 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.