PayStars API unifiée · v3.0
Une seule API.
Le même solde que StarKerak.
Le site, le Telegram WebApp et l’API externe utilisent tous le même solde StarKerak et le même moteur d’exécution. Les commandes par clé API paient le prix Fragment brut sans marge. Les réponses de l’API sont en JSON.
Authentification
Créez une clé API dans le tableau de bord. La clé complète n’est affichée qu’une seule fois. Conservez-la dans l’environnement de votre serveur ; ne la placez jamais dans du JavaScript côté client ni dans un dépôt Git.
X-API-Key: ps_your_secret_api_key Content-Type: application/json Idempotency-Key: order_20260719_0001
Limites, vérification et idempotence
- 10 requêtes par seconde et par clé API.
- Limite de vérification du destinataire via l’API : 120 par minute et par compte ; 12 pour le site/WebApp.
- Avant d’acheter, vous devez appeler
/check-usernameet obtenir unverification_tokenvalable 180 secondes. - Chaque jeton de vérification est lié à exactement une commande logique ; une nouvelle tentative sûre avec la même clé d’idempotence est prise en charge.
- Envoyez une
Idempotency-Keyunique de 8 à 128 caractères avec les achats de Stars et de Premium. - Renvoyer la même
Idempotency-Keyavec la même charge utile ne débite pas à nouveau ; la commande d’origine est renvoyée. - Réutiliser une clé d’idempotence avec une charge utile différente renvoie
409 Conflict.
État de l’API
/statuscurl https://paystars.uz/api/v1/status
Solde et prix en USD
Le compte et le solde en dollars proviennent de StarKerak. Les prix sont en USD : chaque commande passée avec une clé API coûte le prix Fragment brut sans marge (toutes les clés existantes incluses).
/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"
}/pricesPour un prix en USD, utilisez POST /usd/quote (ci-dessous) : avec une clé API, prix = prix Fragment (sans marge).
Vérification du nom d’utilisateur
Ce point de terminaison utilise Fragment pour résoudre le nom, la photo et le statut Premium. Un verification_token n’est renvoyé que pour un destinataire pour lequel un achat est possible.
/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 vaut stars ou premium. Si Premium est déjà actif, vous obtenez premium_active: true, valid: false et un jeton null.
Commande de 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"
}Solde en dollars (USD) et USDT
Les paiements API sont effectués depuis le solde en dollars. Il est rechargé en USDT sur le réseau TON, BEP20 ou TRC20 (minimum 0,1 USDT). Prix en USD via clé API = prix Fragment, sans marge (arrondi au centime supérieur).
/usd/walletSolde en dollars, adresse TON et mémo personnel, adresse BEP20 (avec images 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 est le solde en dollars (chaîne) ; usd.micros : 1 USD = 1 000 000 micros.
/usd/invoice{"amount": 10, "chain": "ton"} ou "chain": "bsc" → un montant exact valable 30 minutes (p. ex. 10.0437). Envoyez exactement ce montant d’USDT à l’adresse sur le réseau choisi (aucun mémo requis pour TON). /usd/bsc-invoice fonctionne encore comme alias hérité (par défaut : bsc).
/usd/invoice/{id}/cancelAnnule une facture en attente (p. ex. pour modifier le montant). Un montant exact annulé n’est attribué à personne d’autre pendant 24 heures, et un paiement arrivant dans ce délai est tout de même crédité sur votre solde.
/usd/invoice/{id}État : pending, paid, expired ou cancelled.
/usd/quote{"kind":"stars","username":"durov","quantity":100} ou {"kind":"premium","username":"durov","months":3} → {"usd": 1.50}.
Pour payer depuis le solde en dollars, ajoutez "currency": "USD" et "max_usd": 1.50 issu de /usd/quote à la charge utile de /stars/buy ou /premium/buy. Si le prix Fragment dépasse max_usd, rien n’est débité et 409 price_changed est renvoyé — obtenez un nouveau devis. Si currency est omis, la préférence de devise enregistrée du compte (pref dans /usd/wallet) est utilisée — envoyez donc toujours "currency": "USD". cost et balance dans la réponse sont dans la devise indiquée par le champ 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}'Commandes
/ordersRenvoie les 50 dernières commandes passées via le site, le WebApp et l’API.
/order/{order_id}curl https://paystars.uz/api/v1/order/1842 \
-H "X-API-Key: $PAYSTARS_API_KEY"Erreurs
| État | Signification | Que faire |
|---|---|---|
| 400 | Charge utile ou clé d’idempotence non valide | Vérifiez le format de la requête |
| 401 | Clé API non valide | Créez une nouvelle clé |
| 402 | Solde USD insuffisant | Rechargez en USDT |
| 409 | Vérification expirée/utilisée ou conflit d’idempotence | Revérifiez le destinataire |
| 422 | Nom d’utilisateur ou service indisponible | Vérifiez le destinataire |
| 402 | insufficient_balance (USD) | Rechargez le solde en dollars avec de l’USDT |
| 409 | price_changed — le prix USD a dépassé max_usd | Obtenez un nouveau /usd/quote |
| 429 | Limite de débit dépassée | Réessayez après Retry-After |
| 503 | Service temporairement indisponible | Utilisez un délai exponentiel |
{
"detail": {
"code": "insufficient_balance",
"message": "StarKerak balance is insufficient"
}
}Exemples fonctionnels
Dans différents langages de programmation
Chaque exemple vérifie le destinataire, obtient le jeton de courte durée et utilise une clé d’idempotence afin que la même commande puisse être réessayée en toute sécurité.
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)
}Intégrez avec une seule invite
Invite IA
Envoyez cette invite à Codex, ChatGPT ou à un autre agent de code. Remplacez les valeurs entre crochets pour les adapter à votre projet.
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.