Português ▾
Dashboard

PayStars API unificada · v3.0

Uma API.
O mesmo saldo do StarKerak.

O site, o Telegram WebApp e a API externa usam o mesmo saldo StarKerak e o mesmo mecanismo de atendimento. Pedidos com chave de API pagam o preço do Fragment 0% (site: 5%). As respostas da API são JSON.

URL base: https://paystars.uz/api/v1. Todo o tráfego deve ser enviado somente por HTTPS.

Autenticação

Crie uma chave de API no Painel. A chave completa é exibida apenas uma vez. Guarde-a no ambiente do servidor; nunca a coloque no JavaScript do frontend nem em um repositório Git.

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

Limites, verificação e idempotência

  • 10 requisições por segundo por chave de API.
  • Limite de verificação de destinatário via API: 120 por minuto por conta; 12 para site/WebApp.
  • Antes de comprar, você deve chamar /check-username e obter um verification_token válido por 180 segundos.
  • Cada token de verificação está vinculado a exatamente um pedido lógico; é possível tentar novamente com segurança usando a mesma chave de idempotência.
  • Envie um Idempotency-Key único de 8–128 caracteres nas compras de Stars e Premium.
  • Reenviar o mesmo Idempotency-Key com a mesma carga útil não cobra de novo; o pedido original é retornado.
  • Reutilizar uma chave de idempotência com uma carga útil diferente retorna 409 Conflict.

Status da API

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

Saldo e preço em USD

A conta e o saldo em dólares vêm do StarKerak. Os preços são em USD: todo pedido feito com uma chave de API custa o preço simples do Fragment, 0% (site: 5%) (todas as chaves existentes incluídas).

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

Para um preço em USD, use POST /usd/quote (abaixo): com uma chave de API, preço = preço do Fragment (0%; site: 5%).

Verificação de nome de usuário

Este endpoint usa o Fragment para resolver o nome, a foto e o status Premium. Um verification_token é retornado apenas para um destinatário para o qual é possível comprar.

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 ou premium. Se o Premium já estiver ativo, você recebe premium_active: true, valid: false e um token null.

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

Pedido de 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 ou 12.

Saldo em dólares (USD) e USDT

Os pagamentos da API são feitos a partir do saldo em dólares. Ele é recarregado com USDT na rede TON, BEP20 ou TRC20 (mínimo de 0,1 USDT). Preço em USD via chave de API = preço do Fragment, 0% (site: 5%) (arredondado para cima até o centavo).

GET/usd/wallet

Saldo em dólares, endereço TON e memo pessoal, endereço BEP20 (com imagens de 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 é o saldo em dólares (string); usd.micros: 1 USD = 1.000.000 micros.

POST/usd/invoice

{"amount": 10, "chain": "ton"} ou "chain": "bsc" → um valor exato válido por 30 minutos (ex.: 10.0437). Envie exatamente essa quantidade de USDT para o endereço na rede escolhida (sem memo necessário para TON). /usd/bsc-invoice continua funcionando como alias legado (padrão: bsc).

POST/usd/invoice/{id}/cancel

Cancela uma fatura pendente (ex.: para alterar o valor). Um valor exato cancelado não é atribuído a mais ninguém por 24 horas, e um pagamento que chegar nesse intervalo ainda é creditado no seu saldo.

GET/usd/invoice/{id}

Status: pending, paid, expired ou cancelled.

POST/usd/quote

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

Para pagar com o saldo em dólares, adicione "currency": "USD" e "max_usd": 1.50 de /usd/quote à carga útil de /stars/buy ou /premium/buy. Se o preço do Fragment exceder max_usd, nada é cobrado e 409 price_changed é retornado — obtenha uma nova cotação. Se currency for omitido, a preferência de moeda salva da conta (pref em /usd/wallet) é usada — então sempre envie "currency": "USD". cost e balance na resposta estão na moeda indicada pelo 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}'

Pedidos

GET/orders

Retorna os 50 pedidos mais recentes feitos pelo site, WebApp e API.

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

Erros

StatusSignificadoO que fazer
400Carga útil ou chave de idempotência inválidaVerifique o formato da requisição
401Chave de API inválidaCrie uma nova chave
402Saldo em USD insuficienteRecarregue com USDT
409Verificação expirada/usada ou conflito de idempotênciaVerifique o destinatário novamente
422Nome de usuário ou serviço indisponívelVerifique o destinatário
402insufficient_balance (USD)Recarregue o saldo em dólares com USDT
409price_changed — o preço em USD excedeu max_usdObtenha uma nova /usd/quote
429Limite de taxa excedidoTente novamente após Retry-After
503Serviço temporariamente indisponívelUse espera exponencial
{
  "detail": {
    "code": "insufficient_balance",
    "message": "StarKerak balance is insufficient"
  }
}

Exemplos funcionais

Em diferentes linguagens de programação

Cada exemplo verifica o destinatário, obtém o token de curta duração e usa uma chave de idempotência para que o mesmo pedido possa ser tentado novamente com segurança.

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

Integre com um único prompt

Prompt de IA

Envie este prompt ao Codex, ChatGPT ou a outro agente de programação. Substitua os valores entre colchetes para adequar ao seu projeto.

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.