Bahasa Melayu ▾
Dashboard

PayStars API Bersepadu · v3.0

Satu API.
Baki yang sama seperti StarKerak.

Laman web, Telegram WebApp dan API luaran semuanya menggunakan baki StarKerak dan enjin pemenuhan yang sama. Pesanan kunci API membayar harga Fragment 0% (situs: 5%). Respons API ialah JSON.

URL asas: https://paystars.uz/api/v1. Semua trafik mesti dihantar melalui HTTPS sahaja.

Pengesahan

Cipta kunci API di Papan Pemuka. Kunci penuh dipaparkan sekali sahaja. Simpan dalam persekitaran pelayan anda; jangan sekali-kali letakkannya dalam JavaScript bahagian hadapan atau repositori Git.

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

Had, pengesahan dan idempotensi

  • 10 permintaan sesaat bagi setiap kunci API.
  • Had semakan penerima melalui API: 120 seminit bagi setiap akaun; 12 untuk laman web/WebApp.
  • Sebelum membeli, anda mesti memanggil /check-username dan mendapatkan verification_token yang sah selama 180 saat.
  • Setiap token pengesahan terikat kepada tepat satu pesanan logik; percubaan semula dengan selamat menggunakan kunci idempotensi yang sama disokong.
  • Hantar Idempotency-Key unik sepanjang 8–128 aksara bersama pembelian Stars dan Premium.
  • Menghantar semula Idempotency-Key yang sama dengan muatan yang sama tidak dicaj semula; pesanan asal dikembalikan.
  • Menggunakan semula kunci idempotensi dengan muatan berbeza mengembalikan 409 Conflict.

Status API

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

Baki dan harga USD

Akaun dan baki dolar datang daripada StarKerak. Harga dalam USD: setiap pesanan yang dibuat dengan kunci API berharga harga Fragment biasa, 0% (situs: 5%) (semua kunci sedia ada termasuk).

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

Untuk harga USD, gunakan POST /usd/quote (di bawah): dengan kunci API, harga = harga Fragment (0%; situs: 5%).

Semakan nama pengguna

Titik akhir ini menggunakan Fragment untuk menyelesaikan nama, foto dan status Premium. verification_token dikembalikan hanya untuk penerima yang boleh dibeli.

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 ialah stars atau premium. Jika Premium sudah aktif, anda mendapat premium_active: true, valid: false dan token null.

Pesanan 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"
}

Pesanan 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 atau 12.

Baki dolar (USD) dan USDT

Pembayaran API dibuat daripada baki dolar. Ia ditambah nilai dengan USDT pada rangkaian TON, BEP20 atau TRC20 (minimum 0.1 USDT). Harga USD melalui kunci API = harga Fragment, 0% (situs: 5%) (dibundarkan ke atas ke sen).

GET/usd/wallet

Baki dolar, alamat TON dan memo peribadi, alamat BEP20 (dengan imej 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 ialah baki dolar (rentetan); usd.micros: 1 USD = 1,000,000 mikro.

POST/usd/invoice

{"amount": 10, "chain": "ton"} atau "chain": "bsc" → jumlah tepat yang sah selama 30 minit (cth. 10.0437). Hantar jumlah USDT yang tepat itu ke alamat pada rangkaian yang dipilih (memo tidak diperlukan untuk TON). /usd/bsc-invoice masih berfungsi sebagai nama lain lama (lalai: bsc).

POST/usd/invoice/{id}/cancel

Membatalkan invois yang belum selesai (cth. untuk menukar jumlah). Jumlah tepat yang dibatalkan tidak diberikan kepada orang lain selama 24 jam, dan pembayaran yang tiba dalam tempoh itu tetap dikreditkan ke baki anda.

GET/usd/invoice/{id}

Status: pending, paid, expired atau cancelled.

POST/usd/quote

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

Untuk membayar daripada baki dolar, tambah "currency": "USD" dan "max_usd": 1.50 daripada /usd/quote ke muatan /stars/buy atau /premium/buy. Jika harga Fragment melebihi max_usd, tiada caj dikenakan dan 409 price_changed dikembalikan — dapatkan sebut harga baharu. Jika currency ditinggalkan, keutamaan mata wang akaun yang disimpan (pref dalam /usd/wallet) digunakan — jadi sentiasa hantar "currency": "USD". cost dan balance dalam respons adalah dalam mata wang yang diberikan oleh medan 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}'

Pesanan

GET/orders

Mengembalikan 50 pesanan terkini yang dibuat melalui laman web, WebApp dan API.

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

Ralat

StatusMaksudApa yang perlu dilakukan
400Muatan atau kunci idempotensi tidak sahSemak format permintaan
401Kunci API tidak sahCipta kunci baharu
402Baki USD tidak mencukupiTambah nilai dengan USDT
409Pengesahan tamat tempoh/telah digunakan atau konflik idempotensiSemak semula penerima
422Nama pengguna atau perkhidmatan tidak tersediaSemak penerima
402insufficient_balance (USD)Tambah nilai baki dolar dengan USDT
409price_changed — harga USD melebihi max_usdDapatkan /usd/quote baharu
429Had kadar telah dilampauiCuba semula selepas Retry-After
503Perkhidmatan tidak tersedia buat sementaraGunakan unduran eksponen
{
  "detail": {
    "code": "insufficient_balance",
    "message": "StarKerak balance is insufficient"
  }
}

Contoh yang berfungsi

Dalam bahasa pengaturcaraan yang berbeza

Setiap contoh menyemak penerima, mendapatkan token jangka pendek dan menggunakan kunci idempotensi supaya pesanan yang sama boleh dicuba semula dengan selamat.

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\"}"

Integrasi dengan satu gesaan

Gesaan AI

Hantar gesaan ini kepada Codex, ChatGPT atau ejen pengekodan lain. Gantikan nilai dalam kurungan agar sesuai dengan projek anda.

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.