Посібник · Telegram Stars

Рахунки Telegram Stars (XTR) у ботах: платіжний процес для розробників крок за кроком

Продаж цифрових товарів за Stars у боті: sendInvoice з XTR, відповідь на pre_checkout_query за 10 секунд, successful_payment, збереження ідентифікатора списання та контрольний список запуску.

Опубліковано:

Рахунки Telegram Stars (XTR) у ботах: платіжний процес для розробників крок за кроком

Ваш бот продає щось цифрове, наприклад підписку, контент, запити до ШІ чи внутрішньоігрові предмети? Тоді оплата лише в Telegram Stars. У цій статті крок за кроком розглянуто процес рахунка Telegram Stars (XTR) з погляду розробника, згідно з офіційною документацією Bot API. Чому це мають бути саме Stars, див. цифрові товари в ботах лише через Stars.

Процес коротко

КрокЩо робить ботЩо надсилає Telegram
1sendInvoice з currency = XTR—
2Очікуєpre_checkout_query
3answerPreCheckoutQuery (протягом 10 секунд)—
4Очікуєsuccessful_payment
5Зберігає ідентифікатор списання, видає товар—

Крок 1: створення рахунку

Є два способи:

  • Рахунок бота: метод sendInvoice. Оскільки товар цифровий, provider_token — порожній рядок, а поле currency — XTR. Рахунок можна надіслати в приватний чат, групу або канал.
  • Вбудований рахунок: якщо бот підтримує вбудований режим, inputInvoiceMessageContent дає змогу ділитися рахунком із друзями, групами й каналами. Його кнопку «Сплатити» можна використовувати багато разів.

Крок 2: вибір поведінки під час пересилання

Це визначає параметр start_parameter:

  1. Рахунок для багатьох чатів: у пересланих копіях лишається кнопка «Сплатити», тож платити можуть багато користувачів. Вбудовані рахунки завжди для багатьох чатів.
  2. Рахунок для одного чату: оплатити його можна лише в чаті, куди його надіслано; у пересланих копіях натомість показано кнопку з прямим посиланням на бота.

Зверніть увагу: рахунок для одного чату, надісланий у приватний чат із вашим ботом, можна оплатити лише один раз. У будь-якому разі бот сам вирішує, чи приймати новий платіж.

Крок 3: попереднє підтвердження

Користувач (за потреби спершу купивши Stars) натискає «Сплатити». Бот отримує pre_checkout_query з деталями замовлення і має відповісти через answerPreCheckoutQuery протягом 10 секунд, інакше транзакцію скасують. Якщо відхиляєте, вкажіть зрозумілу причину; Telegram покаже її користувачеві.

Кроки 4–5: оплата і видача

Коли оплата успішна, надходить повідомлення successful_payment. Лише тоді видавайте товар, бо відповідь на pre_checkout_query не гарантує, що платіж пройшов. Збережіть telegram_payment_charge_id; він знадобиться для повернень.

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

  • Увімкніть двохетапну перевірку для облікового запису, який керує ботом.
  • Надайте умови через /terms, а підтримку — через /support і /paysupport.
  • Будьте готові до спорів і повернень через refundStarPayment. Докладніше в повернення Stars і /paysupport.
  • Тримайте сервер стабільним і робіть резервні копії платіжних даних.

Як тестувати

Окреме тестове середовище Telegram дає змогу безкоштовно тестувати платежі Stars. Коли все працює, переходьте в робоче середовище.

Сторона купівлі Stars

Користувачі купують Stars у застосунку або через @PremiumBot, а PayStars продає їх за USDT. Якщо вашому сервісу потрібно купувати Stars автоматично, це описано в PayStars API та огляді API.

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

Чи можна приймати криптовалюту або іншу валюту замість Stars?

Ні. Цифрові товари й послуги в застосунках Telegram оплачуються лише в Stars.

Як тестувати платежі?

Підключіть бота до окремого тестового середовища Telegram, де платежі Stars можна тестувати безкоштовно.

Як оформити повернення?

Методом refundStarPayment в Bot API.

Джерела

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

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

Почати