Español ▾
Dashboard

PayStars API unificada · v3.0

Una sola API.
El mismo saldo que StarKerak.

El sitio web, Telegram WebApp y la API externa usan el mismo saldo de StarKerak y el mismo motor de tramitación. Los pedidos con clave de API pagan el precio simple de Fragment 0 % (sitio web: 5 %). Las respuestas de la API son JSON.

URL base: https://paystars.uz/api/v1. Todo el tráfico debe enviarse únicamente por HTTPS.

Autenticación

Cree una clave de API en el panel. La clave completa se muestra solo una vez. Guárdela en el entorno de su servidor; nunca la incluya en el JavaScript del cliente ni en un repositorio de Git.

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

Límites, verificación e idempotencia

  • 10 solicitudes por segundo por clave de API.
  • Límite de comprobación de destinatarios vía API: 120 por minuto por cuenta; 12 para el sitio web/WebApp.
  • Antes de comprar debe llamar a /check-username y obtener un verification_token válido durante 180 segundos.
  • Cada token de verificación está vinculado a exactamente un pedido lógico; se admite reintentar de forma segura con la misma clave de idempotencia.
  • Envíe una Idempotency-Key única de 8–128 caracteres con las compras de Stars y Premium.
  • Reenviar la misma Idempotency-Key con la misma carga útil no vuelve a cobrar; se devuelve el pedido original.
  • Reutilizar una clave de idempotencia con una carga útil distinta devuelve 409 Conflict.

Estado de la API

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

Saldo y precio en USD

La cuenta y el saldo en dólares provienen de StarKerak. Los precios están en USD: cada pedido realizado con una clave de API cuesta el precio simple de Fragment, 0 % (sitio web: 5 %) (incluidas todas las claves existentes).

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 un precio en USD use POST /usd/quote (más abajo): con una clave de API, precio = precio de Fragment (0 %; sitio web: 5 %).

Comprobación de nombre de usuario

Este punto de conexión usa Fragment para resolver el nombre, la foto y el estado de Premium. Se devuelve un verification_token solo para un destinatario al que se pueda 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 es stars o premium. Si Premium ya está activo, obtiene premium_active: true, valid: false y un 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 o 12.

Saldo en dólares (USD) y USDT

Los pagos de la API se realizan desde el saldo en dólares. Se recarga con USDT en la red TON, BEP20 o TRC20 (mínimo 0.1 USDT). Precio en USD mediante clave de API = precio de Fragment, 0 % (sitio web: 5 %) (redondeado al alza al centavo).

GET/usd/wallet

Saldo en dólares, dirección de TON y memo personal, dirección BEP20 (con imágenes 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 es el saldo en dólares (cadena); usd.micros: 1 USD = 1,000,000 micros.

POST/usd/invoice

{"amount": 10, "chain": "ton"} o "chain": "bsc" → un importe exacto válido durante 30 minutos (p. ej., 10.0437). Envíe exactamente esa cantidad de USDT a la dirección de la red elegida (no se necesita memo para TON). /usd/bsc-invoice sigue funcionando como alias heredado (predeterminado: bsc).

POST/usd/invoice/{id}/cancel

Cancela una factura pendiente (p. ej., para cambiar el importe). Un importe exacto cancelado no se asigna a nadie más durante 24 horas, y un pago que llegue en ese plazo se abona igualmente a su saldo.

GET/usd/invoice/{id}

Estado: pending, paid, expired o cancelled.

POST/usd/quote

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

Para pagar desde el saldo en dólares, añada "currency": "USD" y "max_usd": 1.50 de /usd/quote a la carga útil de /stars/buy o /premium/buy. Si el precio de Fragment supera max_usd, no se cobra nada y se devuelve 409 price_changed: obtenga una nueva cotización. Si se omite currency, se usa la preferencia de moneda guardada de la cuenta (pref en /usd/wallet); por eso envíe siempre "currency": "USD". cost y balance en la respuesta están en la moneda indicada por el 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

Devuelve los últimos 50 pedidos realizados a través del sitio web, WebApp y la API.

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

Errores

EstadoSignificadoQué hacer
400Carga útil o clave de idempotencia no válidaCompruebe el formato de la solicitud
401Clave de API no válidaCree una clave nueva
402Saldo en USD insuficienteRecargue con USDT
409Verificación caducada/usada o conflicto de idempotenciaVuelva a comprobar el destinatario
422Nombre de usuario o servicio no disponibleCompruebe el destinatario
402insufficient_balance (USD)Recargue el saldo en dólares con USDT
409price_changed — el precio en USD superó max_usdObtenga una nueva /usd/quote
429Límite de frecuencia superadoReintente después de Retry-After
503Servicio temporalmente no disponibleUse una espera exponencial
{
  "detail": {
    "code": "insufficient_balance",
    "message": "StarKerak balance is insufficient"
  }
}

Ejemplos funcionales

En distintos lenguajes de programación

Cada ejemplo comprueba el destinatario, obtiene el token de corta duración y usa una clave de idempotencia para poder reintentar el mismo pedido de forma segura.

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 con una sola indicación

Indicación de IA

Envíe esta indicación a Codex, ChatGPT u otro agente de programación. Sustituya los valores entre corchetes para adaptarlos a su proyecto.

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.