# Payment in Telegram

## 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.

<div data-with-frame="true"><figure><img src="/files/vhaaWoNB6NUxoG1yG0FF" alt="" width="375"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/E1X3WVo2cmBrSRVz4WEC" alt="" width="375"><figcaption></figcaption></figure></div>

Follow the instructions to connect an available payment system and copy the provided token.

<div data-with-frame="true"><figure><img src="/files/jMTzf2EMIdMzzqrFxBz8" alt="" width="375"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/vLdLiPzH707r6wwttFTh" alt="" width="375"><figcaption></figcaption></figure></div>

<div data-with-frame="true"><figure><img src="/files/qxtPhAUAMXpFACdmXaD7" alt="" width="375"><figcaption></figcaption></figure></div>

## **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)**

<table><thead><tr><th width="270">Function parameters</th><th>Parameter description</th></tr></thead><tbody><tr><td><mark style="color:red;"><strong>!</strong></mark> provider_token </td><td>(required parameter) token obtained from BotFather after connecting the payment system</td></tr><tr><td><mark style="color:red;"><strong>!</strong></mark> platform_id </td><td>(required parameter) recipient ID - user, group, or channel identifier</td></tr><tr><td><mark style="color:red;"><strong>!</strong></mark> title </td><td>(required parameter) product title, 1–32 characters</td></tr><tr><td><mark style="color:red;"><strong>!</strong></mark> description </td><td>(required parameter) product description, 1–255 characters</td></tr><tr><td><mark style="color:red;"><strong>!</strong></mark> currency </td><td>(required parameter) payment currency (<mark style="background-color:red;"><strong>EUR</strong></mark>, USD, UAH, etc.; for more details<a href="https://core.telegram.org/bots/payments#supported-currencies"> https://core.telegram.org/bots/payments#supported-currencies</a> )</td></tr><tr><td>prices</td><td><p>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).
<br></p><p>For example: [["product", 2000], ["VAT", 20.75], ["packaging", 100]]</p></td></tr><tr><td>photo_url</td><td>Product image URL</td></tr><tr><td>payload </td><td>The first part of payment callback, default is <strong>tg_payment</strong></td></tr><tr><td>protect_content</td><td>1 - protect from copying and screenshots, 0 - no protection</td></tr><tr><td>disable_notification </td><td>1 - send with notification, 0 - without notification</td></tr><tr><td>need_name</td><td>1 - require full user name to complete order, 0 - no name request</td></tr><tr><td>need_phone_number</td><td>1 - require user phone number to complete order, 0 - no phone number request</td></tr><tr><td>need_email </td><td>1 - require user email to complete order, 0 - no email request</td></tr><tr><td>reply_to_message_id</td><td>Message ID to reply to; if you want to send the invoice as a separate message, use two single quotes ('')</td></tr><tr><td>reply_markup</td><td>Keyboard with the first button set to type <strong>pay</strong></td></tr><tr><td>message_thread_id </td><td>Topic ID (available for supergroups with forum functionality enabled)</td></tr><tr><td>provider_data </td><td>Invoice data in <strong>JSON</strong> format to be sent to payment service provider. Payment system should provide detailed descriptions of required fields.</td></tr></tbody></table>

{% hint style="warning" %}
**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.
{% endhint %}

Example:

<div data-with-frame="true"><figure><img src="/files/vqtUsDOV3JOn12l162cn" alt=""><figcaption></figcaption></figure></div>

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:

<div data-with-frame="true"><figure><img src="/files/dxJMWTm8OXSj8d75ensm" alt=""><figcaption></figcaption></figure></div>

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 <mark style="color:red;">**USD**</mark> 2ff747b9-000f-5000-b000-16d7e3517aa&#x39;**,** where&#x20;

1. course\_pay - payload - the payload from the original invoice creation request;&#x20;
2. 1372995196 - the chat ID where the invoice was originally sent;
3. 120.75 - the total payment amount;
4. <mark style="color:red;">**USD**</mark> - the currency;
5. 2ff747b9-000f-5000-b000-16d7e3517aa9 - the payment ID in the merchant’s system.

<div data-with-frame="true"><figure><img src="/files/B1kpCLWbalJ7w6l2AeSa" alt="" width="563"><figcaption></figcaption></figure></div>

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**

<div data-with-frame="true"><figure><img src="/files/gQiTfv4aBFOdLiRGUlBC" alt="" width="375"><figcaption></figcaption></figure></div>

{% hint style="info" %}
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.
{% endhint %}

{% hint style="info" %}
Once the payment webhook is received, the payment will be automatically confirmed via the answerPreCheckoutQuery method. <https://core.telegram.org/bots/api#answerprecheckoutquery>
{% endhint %}

## 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)**

<table><thead><tr><th width="271">Function parameters</th><th>Description</th></tr></thead><tbody><tr><td><mark style="color:red;"><strong>!</strong></mark><strong> platform_id</strong></td><td>Telegram chat ID <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><strong>message_id</strong> </td><td>Message ID to be pinned</td></tr><tr><td><strong>disable_notification</strong> </td><td>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.
<br>To disable notifications, set the <strong>disable_notification</strong> parameter to 1; otherwise, use 0.</td></tr></tbody></table>

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', '<mark style="color:red;">**USD**</mark>', prices, '<mark style="color:red;">**<https://salebot.pro/promo.png>'**</mark>, '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')

<div data-with-frame="true"><figure><img src="/files/4S676JQIXKcJBf1CRzQj" alt="" width="246"><figcaption></figcaption></figure></div>

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', '<mark style="color:red;">**USD**</mark>', prices)

<div data-with-frame="true"><figure><img src="/files/7olsoHSMnpS5rmKADVvB" alt=""><figcaption></figcaption></figure></div>

### **Example: keyboard**

prices = \[\["course", 100], \["VAT", 20.75]]

tg\_send\_invoice('381764678:TEST:129736', platform\_id, 'Course on courses', 'Creating courses is easy, '<mark style="color:red;">**USD**</mark>', prices, <mark style="color:red;">**'<https://mavibot.ai/promo.png>**</mark>', 'course\_pay','0', '0', '1', '1', '1', '', '{"inline\_keyboard": \[\[{"text":"Pay", "pay":"True"}], \[{"text":"Another button", "callback\_data": "Another button"}]]}')

<div data-with-frame="true"><figure><img src="/files/nnCPdkyBtKQp1sszeHbg" alt=""><figcaption></figcaption></figure></div>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mavibot.ai/chatbot/messengers/telegram/api/payment.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.