Italiano ▾
Dashboard

PayStars API unificata · v3.0

Una sola API.
Lo stesso saldo di StarKerak.

Il sito web, Telegram WebApp e l'API esterna usano tutti lo stesso saldo StarKerak e lo stesso motore di evasione. Gli ordini con chiave API pagano il prezzo Fragment 0% (sito: 5%) aggiuntivo. Le risposte dell'API sono in JSON.

URL di base: https://paystars.uz/api/v1. Tutto il traffico deve essere inviato solo tramite HTTPS.

Autenticazione

Crea una chiave API nel pannello di controllo. La chiave completa viene mostrata una sola volta. Conservala nell'ambiente del server; non inserirla mai nel JavaScript lato client né in un repository Git.

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

Limiti, verifica e idempotenza

  • 10 richieste al secondo per chiave API.
  • Limite di verifica del destinatario tramite API: 120 al minuto per account; 12 per sito web/WebApp.
  • Prima dell'acquisto devi chiamare /check-username e ottenere un verification_token valido per 180 secondi.
  • Ogni token di verifica è associato esattamente a un ordine logico; è supportato il nuovo tentativo sicuro con la stessa chiave di idempotenza.
  • Invia una Idempotency-Key univoca di 8–128 caratteri con gli acquisti di Stars e Premium.
  • Reinviare la stessa Idempotency-Key con gli stessi dati non addebita di nuovo; viene restituito l'ordine originale.
  • Riutilizzare una chiave di idempotenza con dati diversi restituisce 409 Conflict.

Stato dell'API

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

Saldo e prezzo in USD

L'account e il saldo in dollari provengono da StarKerak. I prezzi sono in USD: ogni ordine effettuato con una chiave API costa il prezzo Fragment, 0% (sito: 5%) aggiuntivo (incluse tutte le chiavi esistenti).

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

Per un prezzo in USD usa POST /usd/quote (sotto): con una chiave API, prezzo = prezzo Fragment (0% (sito: 5%) aggiuntivo).

Verifica del nome utente

Questo endpoint usa Fragment per risolvere nome, foto e stato Premium. Un verification_token viene restituito solo per un destinatario per cui è possibile acquistare.

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 è stars o premium. Se Premium è già attivo, ottieni premium_active: true, valid: false e un token null.

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

Ordine 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 o 12.

Saldo in dollari (USD) e USDT

I pagamenti tramite API vengono effettuati dal saldo in dollari. Si ricarica con USDT sulla rete TON, BEP20 o TRC20 (minimo 0,1 USDT). Prezzo in USD con chiave API = prezzo Fragment, 0% (sito: 5%) aggiuntivo (arrotondato per eccesso al centesimo).

GET/usd/wallet

Saldo in dollari, indirizzo TON e memo personale, indirizzo BEP20 (con immagini 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 è il saldo in dollari (stringa); usd.micros: 1 USD = 1.000.000 micros.

POST/usd/invoice

{"amount": 10, "chain": "ton"} o "chain": "bsc" → un importo esatto valido per 30 minuti (ad es. 10.0437). Invia esattamente quell'importo di USDT all'indirizzo sulla rete scelta (nessun memo necessario per TON). /usd/bsc-invoice funziona ancora come alias di compatibilità (predefinito: bsc).

POST/usd/invoice/{id}/cancel

Annulla una fattura in sospeso (ad es. per modificare l'importo). Un importo esatto annullato non viene assegnato a nessun altro per 24 ore e un pagamento che arriva in quella finestra viene comunque accreditato sul tuo saldo.

GET/usd/invoice/{id}

Stato: pending, paid, expired o cancelled.

POST/usd/quote

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

Per pagare dal saldo in dollari, aggiungi "currency": "USD" e "max_usd": 1.50 da /usd/quote al corpo di /stars/buy o /premium/buy. Se il prezzo Fragment supera max_usd, non viene addebitato nulla e viene restituito 409 price_changed — richiedi una nuova quotazione. Se currency viene omesso, si usa la preferenza di valuta salvata dell'account (pref in /usd/wallet) — quindi invia sempre "currency": "USD". cost e balance nella risposta sono nella valuta indicata dal campo 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}'

Ordini

GET/orders

Restituisce gli ultimi 50 ordini effettuati tramite sito web, WebApp e API.

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

Errori

StatoSignificatoCosa fare
400Dati o chiave di idempotenza non validiControlla il formato della richiesta
401Chiave API non validaCrea una nuova chiave
402Saldo USD insufficienteRicarica con USDT
409Verifica scaduta/già usata o conflitto di idempotenzaRicontrolla il destinatario
422Nome utente o servizio non disponibileControlla il destinatario
402insufficient_balance (USD)Ricarica il saldo in dollari con USDT
409price_changed — il prezzo in USD ha superato max_usdOttieni una nuova /usd/quote
429Limite di frequenza superatoRiprova dopo Retry-After
503Servizio temporaneamente non disponibileUsa un'attesa esponenziale
{
  "detail": {
    "code": "insufficient_balance",
    "message": "StarKerak balance is insufficient"
  }
}

Esempi funzionanti

In diversi linguaggi di programmazione

Ogni esempio verifica il destinatario, ottiene il token di breve durata e usa una chiave di idempotenza, così lo stesso ordine può essere ritentato in sicurezza.

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

Integra con un'unica istruzione

Istruzione per l'IA

Invia questa istruzione a Codex, ChatGPT o a un altro agente di programmazione. Sostituisci i valori tra parentesi in base al tuo progetto.

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.