PayStars API для разработчиков: полный цикл продажи Stars и Premium в вашем боте
Как устроен REST API PayStars: X-API-Key, проверка юзернейма, котировка в USD и max_usd, идемпотентные заказы, ошибка 409 price_changed и проверка по TxId — план интеграции.
Опубликовано: · Обновлено:

Хотите продавать Telegram Stars и Premium в своём боте, магазине или приложении? PayStars API — это один HTTPS-интерфейс и общий с сайтом USD-баланс. Эта статья не повторяет справку со страницы API, а показывает, как выстроить интеграцию от начала до конца.
Архитектура в одном взгляде
Ваша система делает три вещи: пополняет баланс в USDT, запрашивает цену и создаёт заказ. Остальное — доставка через официальный механизм покупки Telegram — на стороне PayStars.
| Элемент | Что делает |
|---|---|
| Доступ | Заголовок X-API-Key, ключи создаются в кабинете |
| Баланс | USD, пополняется USDT (TON, BEP20 или TRC20) |
| Цена | Цена Fragment × 1,05 с округлением вверх до цента |
| Лимит | 10 запросов в секунду на ключ |
| Прозрачность | Публичный TxId для каждого выполненного заказа |
Этап 1: пополнение баланса
Запрос POST /usd/invoice с суммой и сетью (chain: "ton", "bsc" или "trc20") возвращает точную сумму, действующую 30 минут. Минимум — 0.1 USDT.
Этап 2: проверка получателя
POST /api/v1/check-username проверяет получателя и возвращает короткоживущий токен подтверждения. Это защищает от оплаты на несуществующий юзернейм: если клиент ошибся, вы узнаете об этом до списания.
Этап 3: получение и ограничение цены
POST /api/v1/usd/quote возвращает текущую цену (usd) и наценку (markup_percent: 5). Цена рыночная, поэтому:
- берите свежую котировку перед каждым заказом;
- передавайте в заказ max_usd, равный сумме котировки;
- всегда отправляйте currency: "USD" — иначе используется сохранённая настройка аккаунта.
Этап 4: создание заказа
POST /api/v1/stars/buy или /api/v1/premium/buy. Каждый запрос обязан содержать Idempotency-Key: если связь оборвалась и вы повторили запрос, второго списания не будет. Храните ключ вместе с ID заказа в своей базе.
Этап 5: отслеживание статуса
GET /api/v1/order/{id} и /api/v1/orders — статусы и история. Большинство заказов доставляется за несколько минут. Выполненный заказ получает TxId, который вы и ваш клиент можете проверить в публичном реестре PayStars.
Правильная обработка ошибок
- 409 price_changed — цена превысила max_usd, ничего не списано. Возьмите новую котировку и покажите клиенту новую цену.
- Превышение лимита — не отправляйте больше 10 запросов в секунду; добавьте очередь или задержку.
- Повторы — всегда с тем же Idempotency-Key.
Перед запуском
- Храните ключ в переменной окружения сервера, не в коде.
- Прогоните весь цикл на небольшом реальном заказе на 50 Stars.
- Показывайте клиенту TxId — это повышает доверие.
Полная документация и быстрые старты: PayStars Stars API и цены API в USD. О платежах внутри бота: цифровые товары в ботах — только за Stars.
Частые вопросы
Есть ли песочница?
Отдельной песочницы нет; при интеграции рекомендуется тестировать небольшими реальными заказами (50 Stars).
На каком языке можно интегрироваться?
На любом, который умеет HTTPS. Есть быстрые старты для Python, Node.js и PHP.
Как пополнить баланс?
USDT в сети TON, BEP20 или TRC20, минимум 0.1 USDT; счёт на точную сумму действует 30 минут.
Источники
Полезные страницы
Покупайте Stars и Premium за USD (USDT)
Через API-ключ: 0% (цена Fragment). Через сайт: 5%.
Другие новости
Telegram Stars и Premium в Узбекистане: оплата картой или USDTКак купить Telegram Stars или Premium в Узбекистане: Uzcard и Humo в @StarKerakBot, USDT на paystars.uz/uz/, официальные способы и местные правила.Читать →
Как наградить победителей конкурса Telegram Stars или Premium: план для организатораКак вручить победителям вашей викторины, конкурса или хакатона Telegram Stars или Premium: бюджет, сбор @username, доставка через PayStars и отчёт.Читать →
PayStars FAQ: частые вопросы о входе, пополнении в USDT, заказах Stars и PremiumСамые частые вопросы о PayStars на одной странице: вход через Telegram, пополнение USDT (TON, BEP20 или TRC20), заказ Stars и Premium, сроки доставки, безопасность и API.Читать →