Посібник · PayStars

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

Як PayStars REST API працює від початку до кінця: 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 із сумою та мережею ("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. Зберігайте ключ API у змінній середовища сервера, а не в коді.
  2. Пройдіть увесь процес із невеликим реальним замовленням на 50 Stars.
  3. Показуйте клієнтам їхній TxId — це зміцнює довіру.

Повна документація та швидкі старти: PayStars Stars API і ціни в USD для API. Про оплату в боті див. цифрові товари в ботах оплачуються лише в Stars.

Запитання й відповіді

Чи є пісочниця?

Окремої пісочниці немає; під час інтеграції тестуйте невеликими реальними замовленнями (50 Stars).

Які мови програмування підходять?

Будь-яка мова, що вміє надсилати запити HTTPS. Є швидкі старти для Python, Node.js і PHP.

Як поповнити баланс?

Через USDT у мережах TON, BEP20 або TRC20, мінімум 0.1 USDT; кожен рахунок має точну суму, дійсну 30 хвилин.

Джерела

Купуйте Stars і Premium за долари США (USDT)

За ключем API: ціна Fragment, 0% (сайт: 5%).

Почати