Гайд · PayStars

PayStars API для разработчиков: полный цикл продажи Stars и Premium в вашем боте

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

Опубликовано: · Обновлено:

PayStars API для разработчиков: полный цикл продажи Stars и Premium в вашем боте

Хотите продавать 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.

Перед запуском

  1. Храните ключ в переменной окружения сервера, не в коде.
  2. Прогоните весь цикл на небольшом реальном заказе на 50 Stars.
  3. Показывайте клиенту 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%.

Начать