Telegram Stars: чому за курс у боті не можна взяти оплату карткою

Ситуація повторюється з підозрілою регулярністю. У клієнта є аудиторія в Telegram, є курс або закритий клуб на продаж, і є підрядник, якому вже пообіцяли «прикрутити еквайринг до бота». Іноді навіть є готовий мерчант-акаунт. Відповідь така: у цьому вигляді зробити не вийде, і це не примха Telegram, яку обходять хитрим інтеграційним трюком. Це правило магазинів застосунків, яке Telegram просто передав вам.

Далі: що саме написано в документації, чому воно так влаштовано, що зобов’язаний вміти бот, який бере гроші, хто платить за спірні транзакції і що курс конвертації Stars робить із вашим прайсом ще до того, як ви назвали цифру.

Формулювання, яке варто прочитати дослівно

Документація Telegram розділена на дві частини, і саме цей поділ і є суттю. Сторінка про фізичні товари та послуги описує звичайні валюти і сторонніх платіжних провайдерів. Сторінка про цифрові товари та послуги описує все інше, і формулювання там не залишає простору для тлумачень: усі платежі через ботів і mini apps за цифрові товари та послуги всередині застосунків Telegram мають здійснюватися виключно в Telegram Stars, щоб відповідати правилам App Store і Play Store.

Технічно це означає, що в полі валюти рахунку стоїть тег XTR, параметр provider_token лишається порожнім, бо стороннього учасника в схемі немає, а користувач платить зірками, які придбав у Telegram заздалегідь. Stars з’явилися у Bot API 7.4 у травні 2024 року, перелік транзакцій додали в 7.5, а підписки за зірки – у 8.0 в листопаді того ж року. Чейнджлог Bot API лишається єдиним джерелом, за яким варто звіряти актуальний набір методів, бо він змінюється кілька разів на рік.

Чому обмеження існує і чому це важливо розуміти

Правило, причину якого ви розумієте, стає передбачуваним. Telegram не залишає її на здогад: щоб відповідати платіжним політикам Google і рекомендаціям Apple з розділів 3.1.1, 3.1.1(a) та 3.1.3(b), бот або mini app має використовувати Stars для продажу цифрових товарів усередині застосунків Telegram, незалежно від того, які сайти, сервіси чи платіжні провайдери ви налаштували за межами екосистеми.

Ланцюжок короткий. Telegram – це застосунок, який поширюється через App Store і Google Play. Обидва магазини вимагають, щоб цифровий контент, який споживається всередині застосунку, продавався через їхні власні механізми внутрішніх покупок. Telegram Stars і є цим механізмом, обгорнутим так, щоб тисячі незалежних ботів користувалися однією відповідною правилам рейкою. Ваш бот живе всередині Telegram, отже ваш бот успадковує обов’язок.

Умови для розробників Bot Platform додають пункт, який зазвичай пробігають очима: Telegram зобов’язаний дотримуватися визначень цифрових товарів і послуг, які дають Apple і Google, ці визначення можуть змінюватися з часом, і розробникам радять звірятися безпосередньо з документацією магазинів. Тобто межу між «цифровим» і «фізичним» проводить не месенджер, і вона не зафіксована назавжди. Якщо ваш продукт стоїть близько до цієї межі, дивитися треба в бік Apple і Google.

Що ви продаєте, чим можна платити, що доведеться реалізувати

Найнеприємніші випадки лежать між п’ятим і шостим рядками. Індивідуальна консультація у відеозв’язку – це не очевидно «фізична послуга», і Telegram не буде розсуджувати це за вас. Орієнтир тут – правила магазинів, а коли класифікація справді неоднозначна, проєктуйте так, щоб оплата відбувалася на вашому сайті, а не в чаті.

Що зобов’язаний уміти бот, який бере гроші

• /terms або настільки ж простий доступ до ваших умов, які покупець має підтвердити до оплати.
• /support або інший чітко озвучений канал підтримки, разом із попередженням, що підтримка Telegram не допоможе з покупками у вашому боті.
• /paysupport – окрема команда саме для платіжних питань, прописана в умовах для розробників. Її забувають найчастіше.
• answerPreCheckoutQuery протягом десяти секунд, інакше транзакція скасовується. Це реальне обмеження для будь-якої синхронної перевірки залишків чи прав доступу.
• Збереження telegram_payment_charge_id з апдейту про успішну оплату. Без нього повернення коштів пізніше зробити неможливо.
• Видача товару тільки після successful_payment. Відповідь на pre-checkout не гарантує платіж, і плутанина тут – класичний спосіб роздати продукт безкоштовно.

Це не складна інженерія. Це приблизно день роботи, який вирішує, чи переживе бот перший спір. Та сама дисципліна стосується і решти сценаріїв: де саме розмовна автоматизація справді замінює людину, а де ні, ми розбирали в матеріалі про Telegram-бота замість менеджера.

Повернення, спори і хто за них платить

Повернення робиться методом refundStarPayment, покупець отримує повну суму, штрафів з боку Telegram немає. Це проста половина. Складна половина прописана в умовах для розробників: обробка законних спорів повністю на продавцеві, Telegram не зобов’язаний бути посередником, а якщо спір завершився поверненням, кошти списуються з вашого балансу.

Telegram іде далі й прямо не рекомендує продавати в реальному часі цифрові продукти та віртуальні предмети, які мають власну цінність і які неможливо забрати назад після успішного чарджбеку покупця. Це варто читати буквально. Якщо ваш продукт споживається миттєво і його не можна відкликати, ризик шахрайства несете ви. Невирішені законні спори можуть коштувати списаних зірок, видалення бота з платформи, публічної позначки scam і блокування акаунта власника.

На практиці це означає власний реєстр доступів поза Telegram, щоб доступ можна було відкликати, коли гроші повернуто. Це вже питання інтеграцій, а не бота, і воно те саме, що ми описували в матеріалі про зв’язку сайту з CRM і обліком.

Економіка без прикрас

Зірки – це не валюта, якою ви володієте. Умови сформульовані жорстко: Stars на балансі бота належать Telegram і не мають власної цінності поза добросовісним зобов’язанням щодо рекламних кредитів і винагород. Значущих ставок дві.

• Винагорода: 0,013 USD за зірку. Саме в це розробник конвертує зірки, обробка йде через Fragment.
• Рекламний кредит: 0,02 USD за зірку. Зірки, витрачені на рекламу власного бота в Telegram, коштують помітно більше, ніж зірки, взяті винагородою.

Є ще затримка: зірки можуть стати доступними для винагороди або реклами не одразу, а протягом двадцяти одного дня після отримання. І окремо Telegram зазначає, що вартість винагороди не має жодного зв’язку з тим, скільки користувач заплатив за зірку в конкретному регіоні. Користувачі купують зірки через внутрішні покупки Apple і Google, тож у роздрібній ціні вже сидять комісія магазину і місцевий ПДВ. Ще одна деталь, критична саме для українських команд: Fragment може бути недоступний для окремих користувачів чи країн, і Telegram прямо знімає з себе відповідальність за такі випадки.

Таблиця – це арифметика на опублікованій Telegram ставці на дату написання, а не прогноз. Telegram зазначає, що визначає цю вартість на власний розсуд і що вона може змінюватися. Звідси два висновки. Перший: спочатку ставте ціну в зірках, а потім переводьте за ставкою винагороди, щоб побачити нижню межу виручки, а не навпаки. Другий: якщо ви й так купуєте рекламу в Telegram, витратити зароблені зірки на рекламу вигідніше, ніж виводити їх, і різниця тут не косметична.

Три архітектури, які працюють

Повний чекаут у зірках усередині бота. Підходить для дешевих і масових цифрових товарів, де вихід із чату вбиває конверсію. Ставка винагороди в цьому випадку – плата за зручність.

Бот як воронка, сайт як каса. Бот кваліфікує, відповідає і передає людину на сторінку, де гроші приймає звичайний провайдер. Усередині Telegram нічого не продається, тож вимога про Stars не застосовується. Це стандартна відповідь для всього з відчутним чеком, і вона лишає клієнтські дані, документи і повернення в системах, які належать вам. Плата – відсів на переході, який вимірюється і зазвичай менший за різницю в ставках.

Розділення за типом товару. Фізика і виїзні послуги через провайдера, цифрові доповнення в зірках, один бот і два потоки. Більше коду, але це ближче до того, як бізнес продає насправді. Наш кейс освітньої платформи і напрям розробки Telegram-ботів побудовані саме на цьому патерні, і він добре стикується з рештою стека, описаного в матеріалі про те, з чого починати автоматизацію маркетингу.

Що вирішити до того, як писати код

• Класифікуйте кожну позицію за визначеннями магазинів, а не за інтуїцією. Класифікація задає платіжну рейку, рейка задає архітектуру.
• Визначте, куди приходять гроші, до того як малювати воронку. Переробити касу дорожче, ніж обрати її з першого разу.
• Рахуйте ціну від ставки винагороди, а не від тієї суми, яку бачить покупець. Різниця між ними не обговорюється.
• Робіть відкликання доступу одночасно з видачею. Повернення – це повноцінний сценарій, а не крайній випадок.
• Викочуйте /paysupport і /terms у першій версії. Зараз це дешево, після скарги – ні.

Коротко

Цифрові товари всередині Telegram оплачуються тільки зірками з тегом XTR, бо Apple і Google вимагають внутрішніх покупок для цифрового контенту, а Telegram передає цю вимогу далі. Фізичні товари і реальні послуги досі можна продавати за звичайні валюти через сторонніх провайдерів. Будь-який бот із оплатою зобов’язаний мати /terms, /support і /paysupport ще до запуску. Повернення йдуть через refundStarPayment, і всю відповідальність за спори та чарджбеки несе продавець, включно з окремим попередженням Telegram про миттєво споживані товари. А ставка винагороди 0,013 USD за зірку проти рекламного кредиту 0,02 USD і затримки до двадцяти одного дня – це вхідні дані для ціноутворення, а не бухгалтерська дрібниця.

Нічого з цього не робить продажі в Telegram поганою ідеєю. Це робить їх проєктним обмеженням, яке або враховують на старті, або виявляють у найгірший момент.