Tiếng Việt ▾
Dashboard

PayStars API hợp nhất · v3.0

Một API.
Cùng số dư với StarKerak.

Website, Telegram WebApp và API bên ngoài đều dùng cùng số dư StarKerak và cùng bộ máy thực hiện đơn. Đơn qua API key trả đúng giá Fragment, 0% (trang web: 5%). Phản hồi API ở dạng JSON.

URL gốc: https://paystars.uz/api/v1. Mọi lưu lượng chỉ được gửi qua HTTPS.

Xác thực

Tạo API key trong Bảng điều khiển. Khóa đầy đủ chỉ hiện một lần. Giữ nó trong môi trường máy chủ; không bao giờ đặt vào JavaScript phía giao diện hoặc kho Git.

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

Giới hạn, xác minh và tính chống trùng

  • 10 yêu cầu mỗi giây cho mỗi API key.
  • Giới hạn kiểm tra người nhận qua API: 120 mỗi phút mỗi tài khoản; 12 cho website/WebApp.
  • Trước khi mua, bạn phải gọi /check-username và lấy verification_token có hiệu lực trong 180 giây.
  • Mỗi token xác minh gắn với đúng một đơn logic; có hỗ trợ thử lại an toàn bằng cùng khóa chống trùng.
  • Gửi Idempotency-Key duy nhất dài 8–128 ký tự khi mua Stars và Premium.
  • Gửi lại cùng Idempotency-Key với cùng dữ liệu sẽ không bị tính phí lần nữa; đơn gốc được trả về.
  • Dùng lại khóa chống trùng với dữ liệu khác sẽ trả về 409 Conflict.

Trạng thái API

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

Số dư và giá USD

Tài khoản và số dư đô la lấy từ StarKerak. Giá tính bằng USD: mọi đơn đặt bằng API key tính đúng giá Fragment, 0% (trang web: 5%) (gồm mọi khóa hiện có).

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

Để lấy giá USD, dùng POST /usd/quote (bên dưới): với API key, giá = giá Fragment (0%; trang web: 5%).

Kiểm tra tên người dùng

Điểm cuối này dùng Fragment để phân giải tên, ảnh và trạng thái Premium. verification_token chỉ được trả về cho người nhận có thể mua cho.

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 là stars hoặc premium. Nếu Premium đã hoạt động, bạn nhận premium_active: true, valid: false và token null.

Đơn 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"
}

Đơn 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 hoặc 12.

Số dư đô la (USD) và USDT

Thanh toán API được trừ từ số dư đô la. Nạp bằng USDT trên mạng TON, BEP20 hoặc TRC20 (tối thiểu 0.1 USDT). Giá USD qua API key = giá Fragment, 0% (trang web: 5%) (làm tròn lên đến xu).

GET/usd/wallet

Số dư đô la, địa chỉ TON và memo cá nhân, địa chỉ BEP20 (kèm ảnh 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 là số dư đô la (chuỗi); usd.micros: 1 USD = 1,000,000 micro.

POST/usd/invoice

{"amount": 10, "chain": "ton"} hoặc "chain": "bsc" → một số tiền chính xác có hiệu lực trong 30 phút (ví dụ 10.0437). Gửi đúng số USDT đó tới địa chỉ trên mạng đã chọn (TON không cần memo). /usd/bsc-invoice vẫn hoạt động như bí danh cũ (mặc định: bsc).

POST/usd/invoice/{id}/cancel

Hủy hóa đơn đang chờ (ví dụ để đổi số tiền). Số tiền chính xác đã hủy không được cấp cho người khác trong 24 giờ, và khoản thanh toán đến trong khoảng đó vẫn được cộng vào số dư của bạn.

GET/usd/invoice/{id}

Trạng thái: pending, paid, expired hoặc cancelled.

POST/usd/quote

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

Để thanh toán từ số dư đô la, thêm "currency": "USD" và "max_usd": 1.50 từ /usd/quote vào dữ liệu của /stars/buy hoặc /premium/buy. Nếu giá Fragment vượt max_usd, không bị tính phí và trả về 409 price_changed — hãy lấy báo giá mới. Nếu bỏ currency, hệ thống dùng tùy chọn tiền tệ đã lưu của tài khoản (pref trong /usd/wallet) — vì vậy luôn gửi "currency": "USD". cost và balance trong phản hồi theo loại tiền do trường currency chỉ định.

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

Đơn hàng

GET/orders

Trả về 50 đơn mới nhất đặt qua website, WebApp và API.

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

Lỗi

Trạng tháiÝ nghĩaCách xử lý
400Dữ liệu hoặc khóa chống trùng không hợp lệKiểm tra định dạng yêu cầu
401API key không hợp lệTạo khóa mới
402Số dư USD không đủNạp bằng USDT
409Xác minh đã hết hạn/đã dùng hoặc xung đột khóa chống trùngKiểm tra lại người nhận
422Tên người dùng hoặc dịch vụ không khả dụngKiểm tra người nhận
402insufficient_balance (USD)Nạp số dư đô la bằng USDT
409price_changed — giá USD vượt max_usdLấy /usd/quote mới
429Vượt giới hạn tần suấtThử lại sau Retry-After
503Dịch vụ tạm thời không khả dụngDùng khoảng chờ tăng theo cấp số nhân
{
  "detail": {
    "code": "insufficient_balance",
    "message": "StarKerak balance is insufficient"
  }
}

Ví dụ chạy được

Bằng các ngôn ngữ lập trình khác nhau

Mỗi ví dụ kiểm tra người nhận, lấy token ngắn hạn và dùng khóa chống trùng để có thể thử lại cùng một đơn một cách an toàn.

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ích hợp bằng một lời nhắc

Lời nhắc AI

Gửi lời nhắc này cho Codex, ChatGPT hoặc tác nhân lập trình khác. Thay các giá trị trong ngoặc cho phù hợp dự án của bạn.

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: plain Fragment price, 0% (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.