TelegramPayment


Специальный тег TelegramPayment позволяет настроить оплату через Telegram.

Описание параметров

Параметр Тип Описание Комментарии Обязательный
providerToken Строка Токен платежной системы Для каждой платежной системы необходимо получить уникальный токен на стороне Telegram. Да
startParameter Логический Разрешать ли клиенту пересылать ссылку на оплату другим клиентам true — другие клиенты смогут оплатить товар или услугу по ссылке.

false — другие клиенты не смогут оплатить товар или услугу по ссылке. Они будут перенаправлены на диалог с ботом.
Да
paymentTitle Строка Название товара или услуги Допустимо не более 32 символов. Да
description Строка Описание товара или услуги Допустимо не более 255 символов. Да
imageUrl Строка Ссылка на изображение Изображение товара или услуги, которое будет отображаться в форме оплаты. Нет
amount Строка Цена товара или услуги Telegram устанавливает ограничения на минимальную и максимальную цену товара или услуги.

Допустимо не более 12 цифр.

Чтобы отделять десятичную часть от целой, используйте точку.
Да
currency Строка Валюта Трехбуквенный код валюты, соответствующий ISO 4217.

Вы можете использовать только те валюты, которые поддерживают Telegram и ваша платежная система.
Да
invoicePayload Строка Произвольные данные для счета-фактуры Данные не будут отображаться в диалоге с клиентом. Они будут отображаться только владельцу кассы для анализа платежей. Да
precheckoutEnabled Логический Проверка наличия товара перед оплатой true — перед оплатой бот будет посылать запросы на URL-адрес сервиса, который указан в поле precheckoutUrl.
Если товара нет в наличии и сервис вернет ответ с HTTP-кодом, отличным от 2xx, то бот перейдет в errorState.
false — бот не будет проверять наличие товара перед оплатой.
Нет
precheckoutUrl Строка URL-адрес сервиса, который возвращает информацию о наличии товара Нет
okState Строка Стейт, в который перейдет диалог, если оплата прошла успешно Нет
errorState Строка Стейт, в который перейдет диалог, если параметры тега заполнены некорректно Сценарий перейдет в указанный стейт, если, например, был указан невалидный токен или цена меньше минимального допустимого значения. Нет
catchAllState Строка Стейт, в который перейдет диалог, если клиент не сможет оплатить счет и отправит произвольное сообщение боту Нет

Подробнее о Telegram Bot Payments API

Получение токена платежной системы

Чтобы принимать платежи от клиентов, необходимо получить уникальный токен платежной системы и указать его в параметре providerToken. Прежде чем получить токен платежной системы, нужно создать бота на стороне Telegram. Выполните шаги, описанные в статье Telegram как входящий канал, и вернитесь к этой статье.

Если у вас уже есть бот в Telegram, то продолжайте читать эту статью.

  1. Откройте Telegram и в поиске контактов введите BotFather.
  2. Отправьте команду /mybots в чат с BotFather.
  3. Выберите бота и нажмите Payments.
  4. Выберите платежную систему из списка.
  5. Выберите один из вариантов подключения:
    • Test для тестирования платежей.
    • Live для настройки реальной интеграции с платежной системой.
  6. Откроется диалог с ботом для выбранной вами платежной системы. Запустите бота.
  7. Выполните все шаги, о которых вас попросит бот платежной системы.
  8. Вернитесь в чат с BotFather.
  9. В последнем сообщении от BotFather вы увидите список подключенных платежных систем к боту и токены для них. Скопируйте нужный токен.
  10. Вставьте скопированный токен в параметр providerToken.

Ограничения на цену

Telegram устанавливает ограничения для каждой валюты на минимальную и максимальную цену товара или услуги. Она должна примерно соответствовать лимиту 1–10 000 USD. Для каждой валюты, кроме USD, эти лимиты зависят от актуальных обменных курсов и могут меняться со временем.

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

Пример использования

state: TelegramPayment
    q!: payment
    TelegramPayment:
        providerToken = {{$injector.providerToken}}
        startParameter = true
        paymentTitle = Билет на Conversations
        description = Конференция, где знают всё о голосовых ассистентах, AI-ботах и технологиях для их создания.
        imageUrl = https://just-ai.com/en/wp-content/uploads/sites/2/2020/10/logo_og-2x-1-1.png
        amount = 17900
        currency = RUB
        invoicePayload = 197110, Санкт-Петербург, ул. Большая Зеленина, 24, стр. 1
        okState = /TelegramPayment/PaymentSuccessful
        errorState = /TelegramPayment/PaymentFailed
        catchAllState = /TelegramPayment/CatchAll

    state: PaymentSuccessful
        a: Оплата прошла успешно. Мы выслали ваш билет на указанный email. До встречи в эфире!
        go!: /SendTickets

    state: PaymentFailed
        a: Возникли неполадки. Пожалуйста, напишите нам на sales@just-ai.com, чтобы купить билет.

    state: CatchAll
        a: Платеж не прошел. Проверьте, пожалуйста, правильность введенных данных и повторите попытку.
        go!: /TelegramPayment

Когда в ходе диалога клиент перейдет в стейт TelegramPayment, в чате появится следующее сообщение:

Оплата в Telegram