Bahasa Indonesia ▾
Dashboard

PayStars API Terpadu · v3.0

Satu API.
Saldo yang sama dengan StarKerak.

Situs web, Telegram WebApp, dan API eksternal memakai saldo StarKerak serta mesin pemenuhan yang sama. Pesanan dengan kunci API membayar harga Fragment 0% (situs: 5%). Respons API berupa JSON.

URL dasar: https://paystars.uz/api/v1. Semua lalu lintas harus dikirim hanya melalui HTTPS.

Autentikasi

Buat kunci API di Dasbor. Kunci lengkap hanya ditampilkan sekali. Simpan di lingkungan server Anda; jangan pernah menaruhnya di JavaScript sisi klien atau repositori Git.

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

Batas, verifikasi, dan idempotensi

  • 10 permintaan per detik per kunci API.
  • Batas pemeriksaan penerima lewat API: 120 per menit per akun; 12 untuk situs web/WebApp.
  • Sebelum membeli, Anda harus memanggil /check-username dan memperoleh verification_token yang berlaku selama 180 detik.
  • Setiap token verifikasi terikat tepat pada satu pesanan logis; percobaan ulang yang aman dengan kunci idempotensi yang sama didukung.
  • Kirim Idempotency-Key unik berisi 8–128 karakter pada pembelian Stars dan Premium.
  • Mengirim ulang Idempotency-Key yang sama dengan muatan yang sama tidak menagih lagi; pesanan asli dikembalikan.
  • Memakai ulang kunci idempotensi dengan muatan berbeda mengembalikan 409 Conflict.

Status API

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

Saldo dan harga USD

Akun dan saldo dolar berasal dari StarKerak. Harga dalam USD: setiap pesanan dengan kunci API dikenai harga Fragment murni, 0% (situs: 5%) (semua kunci yang sudah 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%)).

Pemeriksaan nama pengguna

Titik akhir ini memakai Fragment untuk menentukan nama, foto, dan status Premium. verification_token hanya dikembalikan untuk penerima yang dapat dijadikan tujuan pembelian.

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 adalah 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.

Saldo dolar (USD) dan USDT

Pembayaran API dilakukan dari saldo dolar. Saldo diisi ulang dengan USDT di jaringan TON, BEP20, atau TRC20 (minimum 0,1 USDT). Harga USD lewat kunci API = harga Fragment, 0% (situs: 5%) (dibulatkan ke atas hingga sen).

GET/usd/wallet

Saldo dolar, alamat TON dan memo pribadi, alamat BEP20 (dengan gambar 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 adalah saldo dolar (untaian); usd.micros: 1 USD = 1.000.000 mikro.

POST/usd/invoice

{"amount": 10, "chain": "ton"} atau "chain": "bsc" → jumlah pasti yang berlaku selama 30 menit (mis. 10.0437). Kirim tepat jumlah USDT itu ke alamat di jaringan yang dipilih (memo tidak diperlukan untuk TON). /usd/bsc-invoice tetap berfungsi sebagai alias lama (bawaan: bsc).

POST/usd/invoice/{id}/cancel

Membatalkan faktur yang tertunda (mis. untuk mengubah jumlah). Jumlah pasti yang dibatalkan tidak diberikan kepada orang lain selama 24 jam, dan pembayaran yang tiba dalam jangka itu tetap dikreditkan ke saldo 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 dari saldo dolar, tambahkan "currency": "USD" dan "max_usd": 1.50 dari /usd/quote ke muatan /stars/buy atau /premium/buy. Jika harga Fragment melebihi max_usd, tidak ada yang ditagih dan 409 price_changed dikembalikan — ambil kutipan baru. Jika currency dihilangkan, preferensi mata uang tersimpan akun (pref di /usd/wallet) dipakai — jadi selalu kirim "currency": "USD". cost dan balance dalam respons memakai mata uang yang diberikan oleh bidang 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 terbaru yang dibuat lewat situs web, WebApp, dan API.

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

Kesalahan

StatusArtiYang perlu dilakukan
400Muatan atau kunci idempotensi tidak validPeriksa format permintaan
401Kunci API tidak validBuat kunci baru
402Saldo USD tidak cukupIsi ulang dengan USDT
409Verifikasi kedaluwarsa/terpakai atau konflik idempotensiPeriksa ulang penerima
422Nama pengguna atau layanan tidak tersediaPeriksa penerima
402insufficient_balance (USD)Isi ulang saldo dolar dengan USDT
409price_changed — harga USD melebihi max_usdDapatkan /usd/quote baru
429Batas laju terlampauiCoba lagi setelah Retry-After
503Layanan sementara tidak tersediaGunakan penundaan eksponensial
{
  "detail": {
    "code": "insufficient_balance",
    "message": "StarKerak balance is insufficient"
  }
}

Contoh yang berjalan

Dalam berbagai bahasa pemrograman

Setiap contoh memeriksa penerima, memperoleh token berumur pendek, dan memakai kunci idempotensi agar pesanan yang sama dapat dicoba ulang dengan aman.

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

Integrasikan dengan satu perintah

Perintah AI

Kirim perintah ini ke Codex, ChatGPT, atau agen pemrograman lain. Ganti nilai di dalam tanda kurung agar sesuai proyek 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.