How to connect a payment system
The payment system is built into Telegram. To accept payments within the messenger, you need to:
- Connect a payment system to your bot using BotFather.
- Go to the desired bot settings and select "Payments" from the menu.
Follow the instructions to connect an available payment system and copy the provided token.
How to invoice a client
To send an invoice in Telegram, use the method and specify the required parameters.
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)
| Function parameters | Parameter description |
|---|---|
| **!** provider_token | (required parameter) token obtained from BotFather after connecting the payment system |
| **!** platform_id | (required parameter) recipient ID - user, group, or channel identifier |
| **!** title | (required parameter) product title, 1–32 characters |
| **!** description | (required parameter) product description, 1–255 characters |
| **!** currency | (required parameter) payment currency (**EUR**, USD, UAH, etc.; for more details https://core.telegram.org/bots/payments#supported-currencies ) |
| prices |
An array of arrays containing pricing details for product and additional services (delivery, packaging, etc.). Displayed on the payment page. The amount can be specified as either an integer (e.g., 125) or a decimal number using a dot (e.g., 120.25).
For example: [["product", 2000], ["VAT", 20.75], ["packaging", 100]] |
| photo_url | Product image URL |
| payload | The first part of payment callback, default is tg_payment |
| protect_content | 1 - protect from copying and screenshots, 0 - no protection |
| disable_notification | 1 - send with notification, 0 - without notification |
| need_name | 1 - require full user name to complete order, 0 - no name request |
| need_phone_number | 1 - require user phone number to complete order, 0 - no phone number request |
| need_email | 1 - require user email to complete order, 0 - no email request |
| reply_to_message_id | Message ID to reply to; if you want to send the invoice as a separate message, use two single quotes ('') |
| reply_markup | Keyboard with the first button set to type pay |
| message_thread_id | Topic ID (available for supergroups with forum functionality enabled) |
| provider_data | Invoice data in JSON format to be sent to payment service provider. Payment system should provide detailed descriptions of required fields. |
IMPORTANT! All parameters must be passed in the order specified in the function. If you need to specify a particular parameter and omit others, leave empty values or values as specified in the documentation for the parameters you don’t need.
Example:
If any of the parameters need_name, need_phone_number, or need_email are enabled, the user will be prompted to provide that information before completing payment. Upon successful payment, the data is saved to the corresponding client variables.
Example:
The result: data is requested before payment.
Payment callback
If a payment is successful, a callback with the following content will be sent to the user’s chat:
tg_payment 1372995196 120.75 USD 2ff747b9-000f-5000-b000-16d7e3517aa9, where
- course_pay - payload - the payload from the original invoice creation request;
- 1372995196 - the chat ID where the invoice was originally sent;
- 120.75 - the total payment amount;
- USD - the currency;
- 2ff747b9-000f-5000-b000-16d7e3517aa9 - the payment ID in the merchant’s system.
Additionally, if the user's name, phone number, and/or email were requested, the corresponding variables will be assigned to the client:
tg_payment_name, tg_payment_phone и tg_payment_email
A payment success callback will be sent to the user's direct messages with the bot.
The user must have an existing chat with the bot (i.e., they must have started or subscribed to the bot) before the payment is made. Otherwise, the bot cannot send them the direct message.
Once the payment webhook is received, the payment will be automatically confirmed via the answerPreCheckoutQuery method. https://core.telegram.org/bots/api#answerprecheckoutquery
Pinned message with a payment button
You need to use the message pinning feature after connecting the payment system.
tg_pin_chat_message(platform_id, message_id, disable_notification)
| Function parameters | Description |
|---|---|
| **!** platform_id | Telegram chat ID * |
| message_id | Message ID to be pinned |
| disable_notification | This parameter defines whether a notification should be sent to all chat members about the newly pinned message. Notifications are always disabled in channels and private chats.
To disable notifications, set the disable_notification parameter to 1; otherwise, use 0. |
Example:
Step 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"}]]}')
Step 2:
As a result of the first step, you will receive a response from which you need to extract the message_id value using the get() function.
res=get(result,'result')
m_id=get(res,'message_id')
Next, pin the message: tg_pin_chat_message(#{platform_id}, #{m_id}, 1)
Example: minimal set of parameters
prices = [["super course", 100]]
result= tg_send_invoice('381764678:TEST:129736', platform_id, 'Course on courses', 'Creating courses is super easy', 'USD', prices)
Example: keyboard
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"}]]}')
