Чтобы принимать платежи в Telegram, нужно сделать три вещи:
- Создать бота.
- Подключить его к боту ЮKassa.
- Настроить своего бота для работы с платежами.
Для настройки платежей через бота потребуется параметр
shopId
— он появится у вас после
подключения к ЮKassa.
Чтобы подключить бота к ЮKassa, нужно перевести магазин на email-протокол. Попросите нас об этом по почте
ecommerce@yoomoney.ru или по телефону 8 800 250‒66‒99. Важно: укажите shopId магазина, к которому хотите подключить бота.
В Telegram откройте диалог с
@BotFather, отправьте ему команду
/start, затем —
/newbot.
Придумайте боту имя (name) и юзернейм (username). Имя бота будет в списке контактов и наверху чата, оно может быть неуникальным. Юзернейм будет в короткой ссылке на бота, он должен быть уникальным.
Например:
ЮKassa: платежи — имя бота
YooKassaPaymentBot — это юзернейм бота
Если юзернейм не занят, BotFather пришлет в ответ сообщение с токеном — «ключом» для доступа к созданному боту, его нельзя сообщать посторонним (даже службе поддержки ЮKassa или Telegram).
Когда ключ у вас, бот готов: теперь можно добавить иконку и настроить диалог с клиентами. Одновременно можно настраивать платежи через бота.
Не забудьте перевести магазин на email-протокол. Для этого напишите нам ecommerce@yoomoney.ru или позвоните 8 800 250‒66‒99. Отправьте
@BotFather команду
/mybots. Нажмите на имя своего бота.
Откроется панель управления ботом. Выберите BotSettings — Payments.
Если хотите сразу настроить настоящие платежи, в открывшемся меню выберите Connect ЮKassa: платежи. Если хотите сначала протестировать — выберите Connect ЮKassa: тест.
Если выбран бот ЮKassa: платежи
Если выбран бот ЮKassa: тест
Вернитесь к диалогу с @BotFather. Он пришлёт вам токен, который нужен для выставления счетов. Токен всегда можно посмотреть через BotSettings — Payments.
Обратите внимание: дальше речь пойдёт о настройке бота через API Telegram. Если вы используете конструктор ботов (Manybot, Botobot, Botmaker или любой другой), следуйте его инструкциям.
Реализуйте
метод sendinvoice из платёжного API Telegram: в ответ на этот запрос ваш бот будет отправлять клиенту счёт на оплату. В счёте должна быть стоимость, название, описание товара, параметр
payload
и параметр
provider_token
— это тот самый токен, который выдал @BotFather после подключения вашего бота к боту ЮKassa.
Обратите внимание, что платежи для тестового магазина должны быть не более 1000 рублей.
Посмотреть пример запроса sendinvoice
Если вы настраивали фискализацию через ЮKassa, нужно передавать в ЮKassa данные для фискализации. Для этого добавьте в запрос следующие параметры:
need_phone_number
или need_email
send_email_to_provider
(если вы запрашивали у клиента электронную почту) илиsend_phone_number_to_provider
(если вы запрашивали у клиента телефон),provider_data
и в нём объект
receipt
. Подробности — в
API ЮKassa (смотрите раздел
Атрибуты — receipt).
Телефон или почту вы можете запросить у клиента раньше, в диалоге с ботом. Тогда первые два параметра не нужны, достаточно provider_data
с объектом receipt
.
Если вам нужно получить от клиента адрес для доставки, реализуйте метод Shipping Query. Когда пользователь укажет адрес, на этот запрос нужно ответить методом answerShippingQuery. В этом методе нужно передать способы доставки и их цены.
Когда пользователь подтвердит платёж, Telegram пришлёт вам webhook с Update, который содержит объект PreCheckoutQuery. На этот запрос нужно ответить в течение 10 секунд, вызвав метод answerPreCheckoutQuery.
Если платёж пройдёт успешно, вы получите два уведомления: от Telegram (webhook с объектом SuccessfulPayment) и от ЮKassa (email). Бота можно запрограммировать так, чтобы после успешного платежа он совершал определённое действие: например, подключал покупателю услугу или отправлял контент.
В объекте SuccessfulPayment из уведомления от Telegram найдите параметр provider_payment_charge_id: там будет номер транзакции в ЮKassa. Этот номер лучше сохранить: по нему можно будет найти платёж в личном кабинете.
Обратите внимание: оплата через бота не поддерживается в десктопной и веб-версии Telegram — только в приложении.
Для примера возьмём оплату через тестовый бот ЮKassa — @YooKassaTestShopBot.
Нажмите Запустить (команда /start). Вам придёт сообщение с инструкцией и кнопкой оплаты. В тестовом боте оно выглядит так:
Нажмите Заплатить.
Откроется платёжная форма.
Введите данные карты и нажмите Заплатить.
На странице Checkout нажмите Pay.
После успешной оплаты @YooKassaTestShopBot отправит в чат номер транзакции (для своего бота вы сможете запрограммировать другое действие).