Deutsch ▾
Dashboard

PayStars Einheitliche API · v3.0

Eine API.
Dasselbe Guthaben wie bei StarKerak.

Website, Telegram WebApp und externe API nutzen dasselbe StarKerak-Guthaben und dieselbe Abwicklung. Bestellungen mit API-Schlüssel zahlen den reinen Fragment-Preis, 0 % (Website: 5 %). API-Antworten sind JSON.

Basis-URL: https://paystars.uz/api/v1. Der gesamte Verkehr darf nur über HTTPS gesendet werden.

Authentifizierung

Erstellen Sie einen API-Schlüssel in der Übersicht. Der vollständige Schlüssel wird nur einmal angezeigt. Bewahren Sie ihn in Ihrer Serverumgebung auf; legen Sie ihn niemals in Frontend-JavaScript oder ein Git-Repository.

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

Grenzwerte, Verifizierung und Idempotenz

  • 10 Anfragen pro Sekunde und API-Schlüssel.
  • Limit der Empfängerprüfung über die API: 120 pro Minute und Konto; 12 für Website/WebApp.
  • Vor dem Kauf müssen Sie /check-username aufrufen und ein verification_token erhalten, das 180 Sekunden gültig ist.
  • Jedes Verifizierungs-Token ist genau einer logischen Bestellung zugeordnet; ein sicherer erneuter Versuch mit demselben Idempotenzschlüssel wird unterstützt.
  • Senden Sie bei Käufen von Stars und Premium einen eindeutigen Idempotency-Key mit 8–128 Zeichen.
  • Das erneute Senden desselben Idempotency-Key mit derselben Nutzlast wird nicht erneut berechnet; die ursprüngliche Bestellung wird zurückgegeben.
  • Die Wiederverwendung eines Idempotenzschlüssels mit einer anderen Nutzlast liefert 409 Conflict.

API-Status

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

USD-Guthaben und Preis

Konto und Dollarguthaben stammen von StarKerak. Die Preise sind in USD: Jede Bestellung mit einem API-Schlüssel kostet den reinen Fragment-Preis, 0 % (Website: 5 %) (alle bestehenden Schlüssel eingeschlossen).

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

Für einen USD-Preis verwenden Sie POST /usd/quote (unten): Mit einem API-Schlüssel gilt Preis = Fragment-Preis (0 %; Website: 5 %).

Benutzernamenprüfung

Dieser Endpunkt nutzt Fragment, um Name, Foto und Premium-Status zu ermitteln. Ein verification_token wird nur für einen Empfänger zurückgegeben, für den gekauft werden kann.

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 ist stars oder premium. Wenn Premium bereits aktiv ist, erhalten Sie premium_active: true, valid: false und ein null-Token.

Stars-Bestellung

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

Premium-Bestellung

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 oder 12.

Dollar-Guthaben (USD) und USDT

API-Zahlungen erfolgen aus dem Dollarguthaben. Es wird mit USDT im Netzwerk TON, BEP20 oder TRC20 aufgeladen (mindestens 0,1 USDT). USD-Preis über API-Schlüssel = Fragment-Preis, 0 % (Website: 5 %) (auf den Cent aufgerundet).

GET/usd/wallet

Dollarguthaben, TON-Adresse und persönliches Memo, BEP20-Adresse (mit QR-Bildern).

{
  "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 ist das Dollarguthaben (Zeichenkette); usd.micros: 1 USD = 1.000.000 Micros.

POST/usd/invoice

{"amount": 10, "chain": "ton"} oder "chain": "bsc" → ein exakter Betrag, 30 Minuten gültig (z. B. 10.0437). Senden Sie genau diesen USDT-Betrag an die Adresse im gewählten Netzwerk (für TON ist kein Memo nötig). /usd/bsc-invoice funktioniert weiterhin als älterer Alias (Standard: bsc).

POST/usd/invoice/{id}/cancel

Storniert eine ausstehende Rechnung (z. B. um den Betrag zu ändern). Ein stornierter exakter Betrag wird 24 Stunden lang niemand anderem zugewiesen, und eine in diesem Zeitraum eingehende Zahlung wird weiterhin Ihrem Guthaben gutgeschrieben.

GET/usd/invoice/{id}

Status: pending, paid, expired oder cancelled.

POST/usd/quote

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

Um aus dem Dollarguthaben zu zahlen, fügen Sie "currency": "USD" und "max_usd": 1.50 aus /usd/quote zur Nutzlast von /stars/buy oder /premium/buy hinzu. Übersteigt der Fragment-Preis max_usd, wird nichts berechnet und 409 price_changed zurückgegeben — holen Sie ein neues Angebot. Wird currency weggelassen, gilt die gespeicherte Währungspräferenz des Kontos (pref in /usd/wallet) — senden Sie daher immer "currency": "USD". cost und balance in der Antwort stehen in der Währung des Feldes 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}'

Bestellungen

GET/orders

Gibt die letzten 50 Bestellungen zurück, die über Website, WebApp und API aufgegeben wurden.

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

Fehler

StatusBedeutungWas zu tun ist
400Ungültige Nutzlast oder ungültiger IdempotenzschlüsselPrüfen Sie das Anfrageformat
401Ungültiger API-SchlüsselErstellen Sie einen neuen Schlüssel
402Unzureichendes USD-GuthabenMit USDT aufladen
409Verifizierung abgelaufen/verwendet oder IdempotenzkonfliktPrüfen Sie den Empfänger erneut
422Benutzername oder Dienst nicht verfügbarPrüfen Sie den Empfänger
402insufficient_balance (USD)Laden Sie das Dollarguthaben mit USDT auf
409price_changed — USD-Preis hat max_usd überschrittenHolen Sie ein neues /usd/quote
429Anfragelimit überschrittenErneut versuchen nach Retry-After
503Dienst vorübergehend nicht verfügbarVerwenden Sie einen exponentiellen Wiederholungsabstand
{
  "detail": {
    "code": "insufficient_balance",
    "message": "StarKerak balance is insufficient"
  }
}

Funktionierende Beispiele

In verschiedenen Programmiersprachen

Jedes Beispiel prüft den Empfänger, holt das kurzlebige Token und verwendet einen Idempotenzschlüssel, damit dieselbe Bestellung sicher erneut versucht werden kann.

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

Mit einer einzigen Eingabeaufforderung integrieren

KI-Eingabeaufforderung

Senden Sie diese Eingabeaufforderung an Codex, ChatGPT oder einen anderen Programmieragenten. Ersetzen Sie die Werte in Klammern passend zu Ihrem Projekt.

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.