Настройка модуля «Telegram Pay»

Модуль приема платежей через Telegram Pay / Stars Эта инструкция написана для владельца ADWOS CMS: что подготовить, где включить модуль, какие поля проверить и как понять, что запуск прошел корректно.

Когда стоит подключать модуль

• Площадкам, которые принимают оплату за объявления, заказы, услуги, бронирования или дополнительные опции.
• Владельцам, которым нужно видеть подтвержденный статус платежа внутри ADWOS CMS, а не сверять оплаты вручную.
• Командам, которые хотят сначала проверить тестовую оплату, а затем спокойно включить боевой режим.

Что изменится на сайте

• Пользователь выбирает способ оплаты «Telegram Pay» в платежном сценарии площадки.
• ADWOS CMS получает статус оплаты и может продолжить заказ, бронирование или покупку услуги.
• Владелец площадки разделяет тестовый и боевой режим, чтобы не смешивать проверочные платежи с реальными.
• Ошибки оплаты, отмены и webhook-события проще проверять в одном понятном сценарии.

Что подготовить заранее

Подготовьте доступы и тестовые данные до включения модуля. Так вы проверите сценарий спокойно и не затронете реальные заказы, пользователей или публичные страницы.

• Создайте кабинет мерчанта у провайдера «Telegram Pay» и убедитесь, что он готов к тестовым операциям.
• Подготовьте секретные ключи, webhook-секрет, валюту и адреса страниц успешной оплаты и отмены.
• Проверьте, есть ли у провайдера отдельные ключи для тестового и боевого режима.
• Решите, какой сценарий будет первым тестом: заказ, бронирование, платное объявление или покупка услуги.

Установка в ADWOS CMS

• Откройте административную панель ADWOS CMS под учетной записью администратора.
• В меню выберите раздел «Каталог», затем откройте «Маркетплейс».
• Найдите модуль «Telegram Pay» по названию или через список модулей.
• Если модуль еще не установлен, нажмите «Установить» и дождитесь завершения установки.
• Откройте карточку установленного модуля, выберите «Управлять», затем перейдите в «Настройки».
• Заполните обязательные поля, сохраните настройки и включите модуль переключателем.

Настройка модуля

В настройках модуля заполняйте только те значения, которые относятся к вашему проекту. Секретные ключи храните в защищенных полях и не переносите их в открытые тексты, письма или инструкции для пользователей.

• «Bot Token». Обязательное секретное поле. Вставьте значение из кабинета провайдера и не публикуйте его в описаниях, письмах или открытых страницах. Токен бота от @BotFather (команда /token)
• «Валюта по умолчанию». Укажите валюту, в которой площадка будет работать с этим модулем. Используйте формат, который требует провайдер. Значение по умолчанию: RUB. ISO-4217 (RUB, USD, EUR, KZT, UZS, KGS, BYN). Для Stars укажите XTR.
• «Provider Token». Секретное поле. Вставьте значение из кабинета провайдера и не публикуйте его в описаниях, письмах или открытых страницах. Токен платёжного провайдера от @BotFather , затем Payments. Формат 12345:TEST:abc (тест) или 12345:LIVE:abc (продакшен). Оставьте пустым для оплаты через Telegram Stars (XTR).
• «Site URL». Укажите полный адрес страницы, callback или webhook, который должен использовать внешний сервис. Поле обязательное. Публичный URL вашего сайта без слэша на конце (например https://example.ru). Используется для регистрации webhook у Telegram.
• «Webhook Secret». Секретное поле. Вставьте значение из кабинета провайдера и не публикуйте его в описаниях, письмах или открытых страницах. Секрет для валидации webhook (X-Telegram-Bot-Api-Secret-Token). Если пусто — будет сгенерирован автоматически при сохранении.

После сохранения обновите страницу панели управления и убедитесь, что модуль остался включенным. Если есть тестовый режим, сначала завершите проверку в нем, а уже потом переходите на боевые ключи.

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

• Создайте тестовый заказ или сделку и выберите оплату через «Telegram Pay».
• Проведите тестовую оплату в кабинете провайдера или через тестовую карту, если она доступна.
• Проверьте в ADWOS CMS, что статус заказа изменился автоматически.
• Отдельно проверьте отказ, отмену оплаты и повторный webhook, чтобы увидеть поведение при ошибке.

Частые ошибки

• Статус заказа не меняется после оплаты. Проверьте webhook-секрет, адрес webhook и совпадение тестового или боевого режима.
• Пользователь не возвращается на сайт. Проверьте URL успешной оплаты и URL отмены в настройках модуля и кабинете провайдера.
• Провайдер отклоняет платеж. Проверьте валюту, страну мерчанта, ограничения аккаунта и тестовые реквизиты.
• На сайте не виден способ оплаты. Убедитесь, что модуль включен и доступен для нужного платежного сценария.

Когда тест проходит без ошибок, оставьте модуль включенным и зафиксируйте, какие данные использовались для проверки. Это поможет быстро восстановить настройку после обновления или смены ключей.