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

В 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 Управляет отправкой уведомления о закрепленном сообщении.

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"}]]}'
)