Как подключить платежную систему
Платежная система встроена в Telegram. Чтобы принимать платежи внутри мессенджера, необходимо:
- Подключить платежную систему к вашему боту с помощью BotFather.
- Перейти в настройки нужного бота и выбрать "Payments" в меню.
Следуйте инструкциям для подключения доступной платежной системы и скопируйте предоставленный токен.
Как выставить счет клиенту
Чтобы отправить счет в Telegram, используйте метод и укажите необходимые параметры.
tg_send_invoice(provider_token, platform_id, title, description, currency, prices, photo_url, payload, protect_content, disable_notification, need_name, need_phone_number, need_email, reply_to_message_id, reply_markup, message_thread_id, provider_data)
| Параметры функции | Описание параметра |
|---|---|
| **!** provider_token | (обязательный параметр) токен, полученный от BotFather после подключения платежной системы |
| **!** platform_id | (обязательный параметр) ID получателя — идентификатор пользователя, группы или канала |
| **!** title | (обязательный параметр) название товара, 1–32 символа |
| **!** description | (обязательный параметр) описание товара, 1–255 символов |
| **!** currency | (обязательный параметр) валюта платежа (**EUR**, USD, UAH и т.д.; подробнее https://core.telegram.org/bots/payments#supported-currencies) |
| prices |
Массив массивов, содержащий информацию о ценообразовании товара и дополнительных услуг (доставка, упаковка и т.д.). Отображается на странице оплаты. Сумма может быть указана как целое число (например, 125) или десятичное число с точкой (например, 120.25).
Например: [["product", 2000], ["VAT", 20.75], ["packaging", 100]] |
| photo_url | URL изображения товара |
| payload | Первая часть колбэка платежа, по умолчанию tg_payment |
| protect_content | 1 — защита от копирования и скриншотов, 0 — без защиты |
| disable_notification | 1 — отправить с уведомлением, 0 — без уведомления |
| need_name | 1 — запросить полное имя пользователя для завершения заказа, 0 — не запрашивать имя |
| need_phone_number | 1 — запросить номер телефона пользователя для завершения заказа, 0 — не запрашивать номер телефона |
| need_email | 1 — запросить email пользователя для завершения заказа, 0 — не запрашивать email |
| reply_to_message_id | ID сообщения, на которое нужно ответить; если вы хотите отправить счет как отдельное сообщение, используйте две одинарные кавычки ('') |
| reply_markup | Клавиатура с первой кнопкой типа pay |
| message_thread_id | ID темы (доступно для супергрупп с включенной функцией форума) |
| provider_data | Данные счета в формате JSON, которые будут отправлены поставщику платежных услуг. Платежная система должна предоставить подробные описания обязательных полей. |
ВАЖНО! Все параметры должны передаваться в порядке, указанном в функции. Если вам нужно указать определенный параметр и пропустить другие, оставьте пустые значения или значения, указанные в документации для ненужных вам параметров.
Пример:
Если любой из параметров need_name, need_phone_number или need_email включен, пользователю будет предложено предоставить эту информацию перед завершением платежа. При успешном платеже данные сохраняются в соответствующих переменных клиента.
Пример:
Результат: данные запрашиваются перед оплатой.
Колбэк платежа
При успешном платеже в чат пользователя будет отправлен колбэк со следующим содержимым:
tg_payment 1372995196 120.75 USD 2ff747b9-000f-5000-b000-16d7e3517aa', где
- course_pay - payload - нагрузка из исходного запроса на создание счета;
- 1372995196 - ID чата, в который был отправлен счет;
- 120.75 - общая сумма платежа;
- USD - валюта;
- 2ff747b9-000f-5000-b000-16d7e3517aa9 - ID платежа в системе мерчанта.
Кроме того, если были запрошены имя пользователя, номер телефона и/или email, соответствующие переменные будут присвоены клиенту:
tg_payment_name, tg_payment_phone и tg_payment_email
Колбэк об успешном платеже будет отправлен в личные сообщения пользователя с ботом.
У пользователя должен быть существующий чат с ботом (т.е. он должен был запустить бота или подписаться на него) до совершения платежа. В противном случае бот не сможет отправить ему личное сообщение.
После получения вебхука платежа платеж будет автоматически подтвержден через метод answerPreCheckoutQuery. https://core.telegram.org/bots/api#answerprecheckoutquery
Закрепленное сообщение с кнопкой оплаты
Вам нужно использовать функцию закрепления сообщения после подключения платежной системы.
tg_pin_chat_message(platform_id, message_id, disable_notification)
| Параметры функции | Описание |
|---|---|
| **!** platform_id | ID чата Telegram * |
| message_id | ID сообщения для закрепления |
| disable_notification | Этот параметр определяет, следует ли отправлять уведомление всем участникам чата о новом закрепленном сообщении. В каналах и личных чатах уведомления всегда отключены.
Чтобы отключить уведомления, установите параметр disable_notification в значение 1; в противном случае используйте 0. |
Пример:
Шаг 1:
prices = [["course", 100], ["VAT", 20.75]]
result=tg_send_invoice('381764678:TEST:129736', platform_id, 'Course on courses', 'Creating courses is easy', 'USD', prices, 'https://salebot.pro/promo.png', 'course_pay','0', '0', '1', '1', '1', '', '{"inline_keyboard": [[{"text":"Pay", "pay":"True"}]]}')
Шаг 2:
В результате первого шага вы получите ответ, из которого нужно извлечь значение message_id с помощью функции get().
res=get(result,'result')
m_id=get(res,'message_id')
Затем закрепите сообщение: tg_pin_chat_message(#{platform_id}, #{m_id}, 1)
Пример: минимальный набор параметров
prices = [["super course", 100]]
result= tg_send_invoice('381764678:TEST:129736', platform_id, 'Course on courses', 'Creating courses is super easy', 'USD', prices)
Пример: клавиатура
prices = [["course", 100], ["VAT", 20.75]]
tg_send_invoice('381764678:TEST:129736', platform_id, 'Course on courses', 'Creating courses is easy, 'USD', prices, 'https://mavibot.ai/promo.png', 'course_pay','0', '0', '1', '1', '1', '', '{"inline_keyboard": [[{"text":"Pay", "pay":"True"}], [{"text":"Another button", "callback_data": "Another button"}]]}')
