Як підключити платіжного провайдера

Telegram має вбудовану платіжну систему. Щоб приймати платежі всередині Telegram, потрібно:

  1. Підключити платіжного провайдера до вашого бота через BotFather.
  2. Відкрийте налаштування вашого бота в 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 Масив, що описує позиції рахунку. Кожна позиція містить назву та суму. Суми можуть бути цілими числами або десятковими дробами.

Приклад:
[["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 — запитати адресу електронної пошти покупця.
0 — не запитувати.
reply_to_message_id ID повідомлення, на яке відповідати. Використовуйте '', щоб надіслати рахунок окремим повідомленням.
reply_markup Конфігурація клавіатури. Перша кнопка повинна мати тип pay.
message_thread_id ID теми для супергруп з форумом.
provider_data JSON-об'єкт з даними платежу, специфічними для провайдера. Зверніться до документації вашого платіжного провайдера щодо необхідних полів.

Важливо

Параметри повинні передаватися в точному порядку, вказаному вище.

Якщо потрібно пропустити необов'язкові параметри, залиште їх порожніми або передайте значення за замовчуванням, описані в документації.

Приклад

Якщо увімкнено будь-який з наступних параметрів:

  • need_name
  • need_phone_number
  • need_email

Telegram запитає у покупця необхідну інформацію перед оплатою.

Після успішної оплати зібрана інформація автоматично зберігається у відповідних змінних клієнта.

Приклад:

Колбек платежу

Після успішної оплати Telegram надсилає наступний колбек боту:

tg_payment 1372995196 120.75 USD 2ff747b9-000f-5000-b000-16d7e3517aa9

Де:

  1. tg_payment — значення payload, вказане при створенні рахунку.
  2. 1372995196 — ID чату, куди було надіслано рахунок.
  3. 120.75 — сума платежу.
  4. USD — валюта платежу.
  5. 2ff747b9-000f-5000-b000-16d7e3517aa9 — ID платежу, повернутий платіжним провайдером.

Якщо було запитано інформацію про покупця, наступні змінні клієнта також будуть заповнені автоматично:

  • tg_payment_name
  • tg_payment_phone
  • tg_payment_email

Колбек платежу надсилається в особистий чат користувача з ботом.

Користувач повинен вже розпочати розмову з ботом перед здійсненням платежу. В іншому випадку Telegram не зможе доставити повідомлення колбека.

Після отримання вебхука платежу MaviBot автоматично підтверджує платіж за допомогою методу 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 Керує тим, чи надсилає Telegram сповіщення про закріплене повідомлення.

1 — без сповіщення.
0 — надіслати сповіщення.

Сповіщення завжди вимкнені в особистих чатах та каналах.

Приклад

Крок 1

prices = [["Course", 100], ["VAT", 20.75]]

result = tg_send_invoice(
    '381764678:TEST:129736',
    platform_id,
    'Course',
    '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 з відповіді:

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',
    'Creating courses is super easy',
    'USD',
    prices
)

Приклад: рахунок з інлайн-клавіатурою

prices = [["Course", 100], ["VAT", 20.75]]

tg_send_invoice(
    '381764678:TEST:129736',
    platform_id,
    'Course',
    '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"}]]}'
)