فارسی ▾
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 ثانیه بگیرید.
  • هر توکن تأیید دقیقاً به یک سفارش منطقی وابسته است؛ تلاش مجدد ایمن با همان کلید یکتاسازی پشتیبانی می‌شود.
  • یک Idempotency-Key یکتا با 8–128 نویسه همراه خرید Stars و Premium بفرستید.
  • ارسال دوباره همان 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 (بدون افزایش).

بررسی نام کاربری

این نقطه پایانی از 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.

موجودی دلاری (USD) و USDT

پرداخت‌های API از موجودی دلاری انجام می‌شود. با USDT در شبکه TON، BEP20 یا TRC20 شارژ می‌شود (حداقل 0.1 USDT). قیمت USD با کلید 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}.

برای پرداخت از موجودی دلاری، "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}'

سفارش‌ها

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موجودی 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\"}"

یکپارچه‌سازی با یک دستور

دستور هوش مصنوعی

این دستور را به 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.