Єдиний API PayStars · v3.0
Один API.
Той самий баланс, що й у StarKerak.
Вебсайт, Telegram WebApp і зовнішній API використовують той самий баланс StarKerak і той самий механізм виконання. Замовлення з ключем API оплачуються за прямою ціною Fragment 0% (сайт: 5%). Відповіді API — у форматі JSON.
Автентифікація
Створіть ключ 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
/statuscurl https://paystars.uz/api/v1/status
Баланс і ціна в USD
Обліковий запис і доларовий баланс надходять із StarKerak. Ціни в USD: кожне замовлення з ключем API коштує звичайну ціну Fragment, 0% (сайт: 5%) (включно з усіма наявними ключами).
/accountcurl 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"
}/pricesДля ціни в USD використовуйте POST /usd/quote (нижче): з ключем API ціна = ціна Fragment (0%; сайт: 5%).
Перевірка імені користувача
Ця кінцева точка використовує Fragment, щоб визначити ім’я, фото та статус Premium. verification_token повертається лише для отримувача, якому можна здійснити покупку.
/check-usernamecurl -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
/stars/buycurl -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"
}Доларовий баланс (USD) і USDT
Платежі через API здійснюються з доларового балансу. Його поповнюють USDT у мережі TON, BEP20 або TRC20 (мінімум 0,1 USDT). Ціна в USD за ключем API = ціна Fragment, 0% (сайт: 5%) (округлення вгору до цента).
/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 мікросів.
/usd/invoice{"amount": 10, "chain": "ton"} або "chain": "bsc" → точна сума, дійсна 30 хвилин (наприклад, 10.0437). Надішліть рівно цю кількість USDT на адресу в обраній мережі (для TON примітка не потрібна). /usd/bsc-invoice і далі працює як застарілий псевдонім (типово: bsc).
/usd/invoice/{id}/cancelСкасовує очікуваний рахунок (наприклад, щоб змінити суму). Скасована точна сума не видається нікому іншому протягом 24 годин, а платіж, що надійде в цей період, усе одно зараховується на ваш баланс.
/usd/invoice/{id}Статус: pending, paid, expired або cancelled.
/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}'Замовлення
/ordersПовертає останні 50 замовлень, оформлених через сайт, WebApp і API.
/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 | Ім’я користувача або сервіс недоступні | Перевірте отримувача |
| 402 | insufficient_balance (USD) | Поповніть доларовий баланс через USDT |
| 409 | price_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\"}"import { randomUUID } from 'node:crypto';
const base = 'https://paystars.uz/api/v1';
const headers = { 'X-API-Key': process.env.PAYSTARS_API_KEY, 'Content-Type': 'application/json' };
const verify = await fetch(`${base}/check-username`, {
method: 'POST', headers, body: JSON.stringify({ username: 'telegram', kind: 'stars' })
}).then(async r => { if (!r.ok) throw new Error(await r.text()); return r.json(); });
const order = await fetch(`${base}/stars/buy`, {
method: 'POST', headers: { ...headers, 'Idempotency-Key': `stars_${randomUUID()}` },
body: JSON.stringify({ username: verify.username, quantity: 100, verification_token: verify.verification_token, currency: 'USD' })
}).then(async r => { if (!r.ok) throw new Error(await r.text()); return r.json(); });
console.log(order.order_id, order.status);import os, uuid, requests
base = "https://paystars.uz/api/v1"
headers = {"X-API-Key": os.environ["PAYSTARS_API_KEY"]}
verify = requests.post(f"{base}/check-username", headers=headers,
json={"username": "telegram", "kind": "premium"}, timeout=15)
verify.raise_for_status()
recipient = verify.json()
order = requests.post(f"{base}/premium/buy", headers={
**headers, "Idempotency-Key": f"premium_{uuid.uuid4()}"
}, json={"username": recipient["username"], "months": 3,
"verification_token": recipient["verification_token"], "currency": "USD"}, timeout=20)
order.raise_for_status()
print(order.json())<?php
$base = 'https://paystars.uz/api/v1';
$key = getenv('PAYSTARS_API_KEY');
function postJson($url, $headers, $body) {
$ch = curl_init($url);
curl_setopt_array($ch, [CURLOPT_RETURNTRANSFER => true, CURLOPT_POST => true,
CURLOPT_HTTPHEADER => $headers, CURLOPT_POSTFIELDS => json_encode($body), CURLOPT_TIMEOUT => 20]);
$raw = curl_exec($ch); $status = curl_getinfo($ch, CURLINFO_HTTP_CODE); curl_close($ch);
if ($status < 200 || $status >= 300) throw new RuntimeException($raw);
return json_decode($raw, true, flags: JSON_THROW_ON_ERROR);
}
$common = ["X-API-Key: $key", 'Content-Type: application/json'];
$user = postJson("$base/check-username", $common, ['username' => 'telegram', 'kind' => 'stars']);
$order = postJson("$base/stars/buy", [...$common, 'Idempotency-Key: stars_'.bin2hex(random_bytes(16))],
['username' => $user['username'], 'quantity' => 100, 'verification_token' => $user['verification_token'], 'currency' => 'USD']);
print_r($order);package main
import ("bytes"; "encoding/json"; "fmt"; "io"; "net/http"; "os"; "github.com/google/uuid")
func post(path string, body any, idempotency string, out any) error {
data, _ := json.Marshal(body)
req, _ := http.NewRequest("POST", "https://paystars.uz/api/v1"+path, bytes.NewReader(data))
req.Header.Set("X-API-Key", os.Getenv("PAYSTARS_API_KEY")); req.Header.Set("Content-Type", "application/json")
if idempotency != "" { req.Header.Set("Idempotency-Key", idempotency) }
res, err := http.DefaultClient.Do(req); if err != nil { return err }; defer res.Body.Close()
if res.StatusCode >= 300 { raw, _ := io.ReadAll(res.Body); return fmt.Errorf("API %d: %s", res.StatusCode, raw) }
return json.NewDecoder(res.Body).Decode(out)
}
func main() {
var user struct { Username string `json:"username"`; VerificationToken string `json:"verification_token"` }
if err := post("/check-username", map[string]any{"username":"telegram", "kind":"stars"}, "", &user); err != nil { panic(err) }
var order map[string]any
if err := post("/stars/buy", map[string]any{"username":user.Username, "quantity":100,
"verification_token":user.VerificationToken, "currency":"USD"}, "stars_"+uuid.NewString(), &order); err != nil { panic(err) }
fmt.Println(order)
}Інтегруйте одним промптом
Промпт для ШІ
Надішліть цей промпт до 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: 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.