Guía · PayStars

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:

API de PayStars para desarrolladores: el flujo completo para vender Stars y Premium en tu bot

¿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.

ParteQué hace
AccesoEncabezado X-API-Key; las claves se crean en el panel
SaldoUSD, recargado con USDT (TON, BEP20 o TRC20)
PrecioPrecio de Fragment × 1,05, redondeado al alza al centavo
Límite10 solicitudes por segundo por clave
TransparenciaUn 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

  1. Guarda la clave de API en una variable de entorno del servidor, no en el código.
  2. Ejecuta todo el flujo con un pedido real pequeño de 50 Stars.
  3. 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

Compra Stars y Premium con USD (USDT)

Con clave API: precio de Fragment, 0 % (sitio web: 5 %).

Empezar