Платежи: инвойсы и Telegram Stars

Инвойс — это особое сообщение с кнопкой «Оплатить», которое собирает конфигурация InvoiceConfig, а конструктор tgbotapi.NewInvoice заполняет обязательные поля. Их немного, но каждое работает в платёжной логике: title — название товара до 32 символов, description — строка на экране подтверждения, payload — ваш собственный идентификатор заказа, который Telegram хранит как есть и вернёт после оплаты; его длина — до 128 байт, и в него кладут id заказа из базы. Currency — код валюты, а Prices — срез tgbotapi.LabeledPrice, собранный через NewLabeledPrice(label, amount): сумма в минимальных единицах, для рублей и долларов это копейки и центы, для звёзд — целые штук. Провайдерские инвойсы ещё и разбиваются на компоненты — товар, доставка, скидка, — каждая своим LabeledPrice, и итог считается из этой таблицы. ProviderToken и StartParameter замыкают конфигурацию: токен решает, кто списывает деньги, о нём — следующий раздел.

Фиатные деньги в боте идут через платёжного провайдера: Telegram передаёт инвойс подключённой системе, та списывает средства, а бот получает только подтверждение — сами деньги через Telegram не проходят. Токены выдаются в BotFather разделом /payments: поддерживаются Stripe и региональные провайдеры, список с примерами есть в документации Bot API, а выбор обычно диктуется страной и юридическим статусом продавца. Для разработки у большинства провайдеров есть тестовый режим: тестовые токены и тестовые карты дают возможность пройти всю схему — инвойс, pre-checkout, successful_payment — без единой копейки. Проверять удобно в тестовой среде Telegram Desktop, где клиент работает против песочницы. Честно про сложность: реальный фиат тянет за собой кабинет провайдера, вебхуки о статусах, возвраты и договор — это отдельный проект, и обзорный урок сознательно не притворяется, что покрывает его двадцатью строками. Карта пути та же самая, меняется только обвязка вокруг неё.

Звёзды — внутренняя валюта Telegram, появившаяся в 2024 году, и для цифровых товаров в ботах она стала обязательной дорогой: правила магазинов приложений требуют, чтобы цифровой контент продавался через встроенную оплату, и звёзды — это та самая встроенная оплата. Схема для разработчика почти не меняется: в инвойсе ставится Currency XTR, ProviderToken пустая строка, а суммы в Prices считаются целыми звёздами — никакого деления на сотни. Подтверждение и successful_payment те же, возврат делается методом Bot API refundStarPayment, который свежие обёртки библиотеки дают соответствующей конфигурацией. Звёзды же обслуживают периодические подписки ботов и платные медиа — в этом уроке только отметим их существование, а инвойс в звёздах собирается так же, как обычный: те же поля, другая валюта. Для пет-проекта это идеальный вход в платежи: ни договора с провайдером, ни тестовых карт — минимальный инвойс оплачивается парой звёзд.

Весь диалог денег укладывается в два апдейта и один ответ. PreCheckoutQuery несёт ID запроса, валюту, сумму и ваш payload — достаточно данных, чтобы отказать по делу: товар сняли с продажи, лимит исчерпан, пользователь из заблокированной страны. Ответ конфигурацией PreCheckoutQueryConfig с OK true открывает списание; OK false с ErrorMessage до пары десятков слов объясняет причину — этот текст пользователь увидит в диалоге оплаты. Дальше успешная ветка: SuccessfulPayment внутри Message приносит InvoicePayload, TotalAmount, Currency и пару идентификаторов — TelegramPaymentChargeId и ProviderPaymentChargeId. По payload выдаётся товар, charge_id записывается как факт выдачи и страховка от повторов. Для звёзд на этом всё — деньги уже внутри Telegram; для провайдера начинается его половина работы: чеки, статусы и возвраты в его кабинете. Статусы заказов хранятся у себя — хэш в Redis на каждый payload отлично закрывает эту роль.