हिन्दी ▾
Dashboard

PayStars एकीकृत API · v3.0

एक API.
वही बैलेंस जो StarKerak का है।

वेबसाइट, Telegram WebApp और बाहरी API सभी एक ही StarKerak बैलेंस और पूर्ति इंजन का उपयोग करते हैं। API कुंजी वाले ऑर्डर Fragment कीमत पर बिना अतिरिक्त मार्कअप के चुकाए जाते हैं। 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 कीमत पर आता है, बिना अतिरिक्त मार्कअप (सभी मौजूदा कुंजियाँ शामिल)।

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 कीमत (बिना अतिरिक्त मार्कअप)।

उपयोगकर्ता नाम जाँच

यह एंडपॉइंट नाम, फ़ोटो और 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 कीमत, बिना अतिरिक्त मार्कअप (सेंट तक ऊपर की ओर पूर्णांकित)।

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" और /usd/quote से "max_usd": 1.50 जोड़ें। यदि Fragment कीमत max_usd से अधिक हो, तो कुछ भी नहीं काटा जाता और 409 price_changed लौटाया जाता है — नया कोट प्राप्त करें। यदि currency छोड़ दिया जाए, तो खाते की सहेजी गई मुद्रा प्राथमिकता (/usd/wallet में pref) का उपयोग होता है — इसलिए हमेशा "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.