Polski ▾
Dashboard

PayStars — ujednolicone API · v3.0

Jedno API.
To samo saldo co StarKerak.

Strona internetowa, Telegram WebApp i zewnętrzne API korzystają z tego samego salda StarKerak i silnika realizacji zamówień. Zamówienia z kluczem API płacą cenę Fragment 0% (strona: 5%). Odpowiedzi API są w JSON.

Bazowy URL: https://paystars.uz/api/v1. Cały ruch musi być wysyłany wyłącznie przez HTTPS.

Uwierzytelnianie

Utwórz klucz API w panelu. Pełny klucz jest pokazywany tylko raz. Przechowuj go w środowisku serwera; nigdy nie umieszczaj go w klienckim JavaScript ani w repozytorium Git.

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

Limity, weryfikacja i idempotencja

  • 10 żądań na sekundę na klucz API.
  • Limit sprawdzania odbiorcy przez API: 120 na minutę na konto; 12 dla strony/WebApp.
  • Przed zakupem musisz wywołać /check-username i uzyskać verification_token ważny przez 180 sekund.
  • Każdy token weryfikacji jest przypisany do dokładnie jednego logicznego zamówienia; obsługiwane jest bezpieczne ponawianie z tym samym kluczem idempotencji.
  • Wyślij unikalny Idempotency-Key o długości 8–128 znaków przy zakupach Stars i Premium.
  • Ponowne wysłanie tego samego Idempotency-Key z tymi samymi danymi nie powoduje ponownego obciążenia; zwracane jest pierwotne zamówienie.
  • Ponowne użycie klucza idempotencji z innymi danymi zwraca 409 Conflict.

Status API

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

Saldo i cena w USD

Konto i saldo dolarowe pochodzą ze StarKerak. Ceny są w USD: każde zamówienie złożone kluczem API kosztuje samą cenę Fragment, 0% (strona: 5%) (obejmuje wszystkie istniejące klucze).

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

Aby uzyskać cenę w USD, użyj POST /usd/quote (poniżej): z kluczem API cena = cena Fragment (0%; strona: 5%).

Sprawdzanie nazwy użytkownika

Ta metoda korzysta z Fragment, aby ustalić nazwę, zdjęcie i status Premium. verification_token jest zwracany tylko dla odbiorcy, dla którego można dokonać zakupu.

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 to stars lub premium. Jeśli Premium jest już aktywne, otrzymujesz premium_active: true, valid: false i token null.

Zamówienie 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"
}

Zamówienie 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 lub 12.

Saldo dolarowe (USD) i USDT

Płatności API są realizowane z salda dolarowego. Doładowuje się je USDT w sieci TON, BEP20 lub TRC20 (minimum 0,1 USDT). Cena w USD przez klucz API = cena Fragment, 0% (strona: 5%) (zaokrąglenie w górę do centa).

GET/usd/wallet

Saldo dolarowe, adres TON i osobiste memo, adres BEP20 (z obrazami 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 to saldo dolarowe (ciąg znaków); usd.micros: 1 USD = 1 000 000 mikrojednostek.

POST/usd/invoice

{"amount": 10, "chain": "ton"} lub "chain": "bsc" → dokładna kwota ważna przez 30 minut (np. 10.0437). Wyślij dokładnie tę ilość USDT na adres w wybranej sieci (dla TON memo nie jest potrzebne). /usd/bsc-invoice nadal działa jako starszy alias (domyślnie: bsc).

POST/usd/invoice/{id}/cancel

Anuluje oczekującą fakturę (np. aby zmienić kwotę). Anulowana dokładna kwota nie trafia do nikogo innego przez 24 godziny, a płatność, która nadejdzie w tym czasie, i tak zostanie zaksięgowana na Twoim saldzie.

GET/usd/invoice/{id}

Status: pending, paid, expired lub cancelled.

POST/usd/quote

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

Aby zapłacić z salda dolarowego, dodaj "currency": "USD" oraz "max_usd": 1.50 z /usd/quote do treści żądania /stars/buy lub /premium/buy. Jeśli cena Fragment przekroczy max_usd, nic nie zostanie pobrane i zwrócone zostanie 409 price_changed — pobierz nową wycenę. Jeśli pominięto currency, używana jest zapisana preferencja waluty konta (pref w /usd/wallet) — dlatego zawsze wysyłaj "currency": "USD". cost i balance w odpowiedzi są w walucie wskazanej przez pole 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}'

Zamówienia

GET/orders

Zwraca ostatnie 50 zamówień złożonych przez stronę, WebApp i API.

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

Błędy

StatusZnaczenieCo zrobić
400Nieprawidłowe dane lub klucz idempotencjiSprawdź format żądania
401Nieprawidłowy klucz APIUtwórz nowy klucz
402Niewystarczające saldo USDDoładuj USDT
409Weryfikacja wygasła/użyta lub konflikt idempotencjiSprawdź odbiorcę ponownie
422Nazwa użytkownika lub usługa niedostępnaSprawdź odbiorcę
402insufficient_balance (USD)Doładuj saldo dolarowe USDT
409price_changed — cena USD przekroczyła max_usdPobierz nowy /usd/quote
429Przekroczono limit żądańPonów po Retry-After
503Usługa tymczasowo niedostępnaUżyj wykładniczego opóźnienia
{
  "detail": {
    "code": "insufficient_balance",
    "message": "StarKerak balance is insufficient"
  }
}

Działające przykłady

W różnych językach programowania

Każdy przykład sprawdza odbiorcę, uzyskuje krótkotrwały token i używa klucza idempotencji, aby to samo zamówienie można było bezpiecznie ponowić.

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

Integracja jednym poleceniem

Polecenie AI

Wyślij to polecenie do Codex, ChatGPT lub innego agenta kodującego. Zastąp wartości w nawiasach, aby dopasować je do swojego projektu.

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.