API de PayStars para desarrolladores: el flujo completo para vender Stars y Premium en tu bot
Cómo funciona la API REST de PayStars de principio a fin: X-API-Key, comprobaciones de nombres de usuario, cotizaciones en USD con max_usd, pedidos idempotentes, el error 409 price_changed y la verificación de TxId, como plan de integración.
Publicado: · Actualizado:

¿Quieres vender Telegram Stars y Premium dentro de tu propio bot, tienda o aplicación? La API de PayStars te ofrece una interfaz HTTPS y un saldo en USD compartido con el sitio web. En lugar de repetir la referencia de la API, este artículo muestra cómo construir la integración de principio a fin.
La arquitectura de un vistazo
Tu sistema hace tres cosas: recarga el saldo con USDT, pide un precio y crea un pedido. Todo lo demás, incluida la entrega a través del flujo oficial de compra de Telegram, ocurre del lado de PayStars.
| Parte | Qué hace |
|---|---|
| Acceso | Encabezado X-API-Key; las claves se crean en el panel |
| Saldo | USD, recargado con USDT (TON, BEP20 o TRC20) |
| Precio | Precio de Fragment × 1,05, redondeado al alza al centavo |
| Límite | 10 solicitudes por segundo por clave |
| Transparencia | Un TxId público para cada pedido completado |
Etapa 1: recargar el saldo
POST /usd/invoice con un importe y una cadena ("ton", "bsc" o "trc20") devuelve un importe exacto válido durante 30 minutos. El mínimo es 0,1 USDT.
Etapa 2: verificar el destinatario
POST /api/v1/check-username comprueba el destinatario y devuelve un token de verificación de corta duración. Eso evita pagos a nombres de usuario que no existen: si un cliente comete un error tipográfico, te enteras antes de que se cobre nada.
Etapa 3: obtener y limitar el precio
POST /api/v1/usd/quote devuelve el precio actual (usd) y el recargo (markup_percent: 5). El precio sigue el mercado, así que:
- solicita una cotización reciente antes de cada pedido;
- pasa max_usd igual al importe cotizado;
- envía siempre currency: "USD"; de lo contrario, se usa la preferencia guardada de la cuenta.
Etapa 4: crear el pedido
POST /api/v1/stars/buy o /api/v1/premium/buy. Cada solicitud debe incluir un Idempotency-Key, de modo que si se corta la conexión y reintentas, no se te cobre dos veces. Guarda la clave junto con el ID del pedido en tu base de datos.
Etapa 5: seguir el estado
GET /api/v1/order/{id} y /api/v1/orders te dan estados e historial. La mayoría de los pedidos se entregan en minutos. Un pedido completado recibe un TxId que tanto tú como tu cliente pueden consultar en el registro público de PayStars.
Gestionar los errores correctamente
- 409 price_changed significa que el precio superó max_usd y no se cobró nada. Obtén una nueva cotización y muestra al cliente el precio actualizado.
- Límite de frecuencia: no superes 10 solicitudes por segundo; añade una cola o un retardo progresivo.
- Reintentos: reutiliza siempre el mismo Idempotency-Key.
Antes de pasar a producción
- Guarda la clave de API en una variable de entorno del servidor, no en el código.
- Ejecuta todo el flujo con un pedido real pequeño de 50 Stars.
- Muestra a los clientes su TxId, lo que genera confianza.
Documentación completa y guías de inicio rápido: API de Stars de PayStars y precios en USD para la API. Para pagos dentro del bot, consulta los bienes digitales en los bots se pagan solo con Stars.
Preguntas frecuentes
¿Hay un entorno de pruebas?
No hay un entorno de pruebas separado; prueba con pedidos reales pequeños (50 Stars) mientras integras.
¿Qué lenguajes de programación funcionan?
Cualquier lenguaje que pueda hacer solicitudes HTTPS. Hay guías de inicio rápido para Python, Node.js y PHP.
¿Cómo recargo el saldo?
Con USDT en TON, BEP20 o TRC20, mínimo 0,1 USDT; cada factura tiene un importe exacto válido durante 30 minutos.
Fuentes
Related pages
Compra Stars y Premium con USD (USDT)
Con clave API: precio de Fragment, 0 % (sitio web: 5 %).
More news
Telegram Stars y Premium en Uzbekistán: pague con tarjeta o con USDTComprar Telegram Stars o Premium en Uzbekistán: Uzcard y Humo a través de @StarKerakBot, USDT en paystars.uz/uz/, las vías de la app oficial y las normas locales que conviene conocer.Leer →
Cómo premiar a los ganadores de un concurso con Telegram Stars o Premium: guía para organizadoresEntrega de Telegram Stars o Premium a los ganadores de tu propio cuestionario, concurso o hackatón: presupuesto, recopilación de @usernames, entrega a través de PayStars y un informe de seguimiento.Leer →
Preguntas frecuentes de PayStars: dudas habituales sobre el inicio de sesión, recargas con USDT y pedidos de Stars y PremiumLas preguntas más frecuentes de PayStars en una sola página: inicio de sesión con Telegram, recarga con USDT (TON, BEP20 o TRC20), pedidos de Stars y Premium, plazos de entrega, seguridad y la API.Leer →