Як підключити платіжну систему
Платіжна система вбудована в 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 | (обов'язковий параметр) ідентифікатор отримувача - користувача, групи або каналу |
| **!** 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"}]]}')
