How to connect a payment provider

Telegram has a built-in payment system. To accept payments inside Telegram, you need to:

  1. Connect a payment provider to your bot through BotFather.
  2. Open your bot settings in BotFather and select Payments.

Follow the instructions to connect one of the available payment providers, then copy the generated provider token.

How to send an invoice

To send an invoice in Telegram, use the following function:

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
)
Parameter Description
provider_token Required. Provider token received from BotFather after connecting your payment provider.
platform_id Required. Recipient identifier (user, group, or channel ID).
title Required. Product title (1–32 characters).
description Required. Product description (1–255 characters).
currency Required. Payment currency (for example: EUR, USD, UAH). See the list of supported currencies: https://core.telegram.org/bots/payments#supported-currencies
prices Array describing the invoice items. Each item contains a title and an amount. Amounts may be integers or decimal numbers.

Example:
[["Product", 2000], ["VAT", 20.75], ["Packaging", 100]]
photo_url URL of the product image.
payload Custom payload returned in the payment callback. Default: tg_payment.
protect_content 1 — protect content from copying and screenshots.
0 — no protection.
disable_notification 1 — send silently.
0 — send with notification.
need_name 1 — request the customer's full name.
0 — do not request it.
need_phone_number 1 — request the customer's phone number.
0 — do not request it.
need_email 1 — request the customer's email address.
0 — do not request it.
reply_to_message_id Message ID to reply to. Use '' to send the invoice as a separate message.
reply_markup Keyboard configuration. The first button must have the pay type.
message_thread_id Topic ID for forum-enabled supergroups.
provider_data JSON object with provider-specific payment data. Refer to your payment provider's documentation for the required fields.

Important

Parameters must be passed in the exact order shown above.

If you need to skip optional parameters, leave them empty or pass the default values described in the documentation.

Example

If any of the following parameters are enabled:

  • need_name
  • need_phone_number
  • need_email

Telegram will ask the customer for the requested information before payment.

After a successful payment, the collected information is automatically saved to the corresponding client variables.

Example:

Payment callback

After a successful payment, Telegram sends the following callback to the bot:

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

Where:

  1. tg_payment — the payload value specified when creating the invoice.
  2. 1372995196 — the chat ID where the invoice was originally sent.
  3. 120.75 — the payment amount.
  4. USD — the payment currency.
  5. 2ff747b9-000f-5000-b000-16d7e3517aa9 — the payment ID returned by the payment provider.

If customer information was requested, the following client variables will also be populated automatically:

  • tg_payment_name
  • tg_payment_phone
  • tg_payment_email

The payment callback is sent to the user's private chat with the bot.

The user must have already started a conversation with the bot before making the payment. Otherwise, Telegram cannot deliver the callback message.

After receiving the payment webhook, MaviBot automatically confirms the payment using the answerPreCheckoutQuery method.

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

Pinning an invoice message

After connecting a payment provider, you can pin the invoice message.

Use the function:

tg_pin_chat_message(platform_id, message_id, disable_notification)
Parameter Description
platform_id Telegram chat ID.
message_id ID of the message to pin.
disable_notification Controls whether Telegram sends a notification about the pinned message.

1 — no notification.
0 — send notification.

Notifications are always disabled in private chats and channels.

Example

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

Step 2

Extract the message_id from the response:

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

Then pin the message:

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

Example: minimum required parameters

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

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

Example: invoice with an inline keyboard

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