Cómo conectar un proveedor de pagos

Telegram tiene un sistema de pago integrado. Para aceptar pagos dentro de Telegram, debes:

  1. Conectar un proveedor de pagos a tu bot a través de BotFather.
  2. Abrir la configuración de tu bot en BotFather y seleccionar Payments.

Sigue las instrucciones para conectar uno de los proveedores de pago disponibles, luego copia el token de proveedor generado.

Cómo enviar una factura

Para enviar una factura en Telegram, usa la siguiente función:

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
)
Parámetro Descripción
provider_token Requerido. Token de proveedor recibido de BotFather después de conectar tu proveedor de pagos.
platform_id Requerido. Identificador del destinatario (ID de usuario, grupo o canal).
title Requerido. Título del producto (1–32 caracteres).
description Requerido. Descripción del producto (1–255 caracteres).
currency Requerido. Moneda de pago (por ejemplo: EUR, USD, UAH). Consulta la lista de monedas compatibles: https://core.telegram.org/bots/payments#supported-currencies
prices Array que describe los artículos de la factura. Cada artículo contiene un título y un monto. Los montos pueden ser números enteros o decimales.

Ejemplo:
[["Product", 2000], ["VAT", 20.75], ["Packaging", 100]]
photo_url URL de la imagen del producto.
payload Carga útil personalizada devuelta en el callback de pago. Valor predeterminado: tg_payment.
protect_content 1 — proteger el contenido contra copias y capturas de pantalla.
0 — sin protección.
disable_notification 1 — enviar silenciosamente.
0 — enviar con notificación.
need_name 1 — solicitar el nombre completo del cliente.
0 — no solicitarlo.
need_phone_number 1 — solicitar el número de teléfono del cliente.
0 — no solicitarlo.
need_email 1 — solicitar la dirección de correo electrónico del cliente.
0 — no solicitarla.
reply_to_message_id ID del mensaje al que responder. Usa '' para enviar la factura como un mensaje separado.
reply_markup Configuración del teclado. El primer botón debe tener el tipo pay.
message_thread_id ID del tema para supergrupos con foro habilitado.
provider_data Objeto JSON con datos de pago específicos del proveedor. Consulta la documentación de tu proveedor de pagos para conocer los campos requeridos.

Importante

Los parámetros deben pasarse en el orden exacto que se muestra arriba.

Si necesitas omitir parámetros opcionales, déjalos vacíos o pasa los valores predeterminados descritos en la documentación.

Ejemplo

Si alguno de los siguientes parámetros está habilitado:

  • need_name
  • need_phone_number
  • need_email

Telegram solicitará al cliente la información solicitada antes del pago.

Después de un pago exitoso, la información recopilada se guarda automáticamente en las variables de cliente correspondientes.

Ejemplo:

Callback de pago

Después de un pago exitoso, Telegram envía el siguiente callback al bot:

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

Donde:

  1. tg_payment — el valor de payload especificado al crear la factura.
  2. 1372995196 — el ID del chat donde se envió originalmente la factura.
  3. 120.75 — el monto del pago.
  4. USD — la moneda del pago.
  5. 2ff747b9-000f-5000-b000-16d7e3517aa9 — el ID de pago devuelto por el proveedor de pagos.

Si se solicitó información del cliente, las siguientes variables de cliente también se completarán automáticamente:

  • tg_payment_name
  • tg_payment_phone
  • tg_payment_email

El callback de pago se envía al chat privado del usuario con el bot.

El usuario debe haber iniciado una conversación con el bot antes de realizar el pago. De lo contrario, Telegram no puede entregar el mensaje de callback.

Después de recibir el webhook de pago, MaviBot confirma automáticamente el pago usando el método answerPreCheckoutQuery.

https://core.telegram.org/bots/api#answerprecheckoutquery

Fijar un mensaje de factura

Después de conectar un proveedor de pagos, puedes fijar el mensaje de la factura.

Usa la función:

tg_pin_chat_message(platform_id, message_id, disable_notification)
Parámetro Descripción
platform_id ID del chat de Telegram.
message_id ID del mensaje a fijar.
disable_notification Controla si Telegram envía una notificación sobre el mensaje fijado.

1 — sin notificación.
0 — enviar notificación.

Las notificaciones siempre están deshabilitadas en chats privados y canales.

Ejemplo

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

Paso 2

Extrae el message_id de la respuesta:

res = get(result, 'result')
m_id = get(res, 'message_id')

Luego fija el mensaje:

tg_pin_chat_message(#{platform_id}, #{m_id}, 1)

Ejemplo: parámetros mínimos requeridos

prices = [["Super course", 100]]

result = tg_send_invoice(
    '381764678:TEST:129736',
    platform_id,
    'Course',
    'Creating courses is super easy',
    'USD',
    prices
)

Ejemplo: factura con un teclado inline

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