PayStars API для розробників: повний процес продажу Stars і Premium у вашому боті
Як PayStars REST API працює від початку до кінця: 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 із сумою та мережею ("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.
Перед запуском
- Зберігайте ключ API у змінній середовища сервера, а не в коді.
- Пройдіть увесь процес із невеликим реальним замовленням на 50 Stars.
- Показуйте клієнтам їхній TxId — це зміцнює довіру.
Повна документація та швидкі старти: PayStars Stars API і ціни в USD для API. Про оплату в боті див. цифрові товари в ботах оплачуються лише в Stars.
Запитання й відповіді
Чи є пісочниця?
Окремої пісочниці немає; під час інтеграції тестуйте невеликими реальними замовленнями (50 Stars).
Які мови програмування підходять?
Будь-яка мова, що вміє надсилати запити HTTPS. Є швидкі старти для Python, Node.js і PHP.
Як поповнити баланс?
Через USDT у мережах TON, BEP20 або TRC20, мінімум 0.1 USDT; кожен рахунок має точну суму, дійсну 30 хвилин.
Джерела
Related pages
Купуйте Stars і Premium за долари США (USDT)
За ключем API: ціна Fragment, 0% (сайт: 5%).
More news
Telegram Stars і Premium в Узбекистані: оплата карткою або через USDTКупівля Telegram Stars або Premium в Узбекистані: Uzcard і Humo через @StarKerakBot, USDT на paystars.uz/uz/, офіційні способи в застосунку та місцеві правила, які варто знати.Читати →
Як нагороджувати переможців конкурсів Telegram Stars або Premium: посібник організатораДоставка Telegram Stars або Premium переможцям власної вікторини, конкурсу чи хакатону: бюджет, збір @usernames, доставка через PayStars і підсумковий звіт.Читати →
Часті запитання PayStars: вхід, поповнення USDT і замовлення Stars та PremiumНайпоширеніші запитання про PayStars на одній сторінці: вхід через Telegram, поповнення USDT (TON, BEP20 або TRC20), замовлення Stars і Premium, терміни доставки, безпека та API.Читати →