# Оплата в Telegram

## Як підключити платіжну систему

Платіжна система вбудована в Telegram. Щоб приймати платежі всередині месенджера, потрібно:

* Підключити платіжну систему до свого бота за допомогою **BotFather**.
* Перейдіть до налаштувань потрібного бота та виберіть **«Платежі»** у меню.

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

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

Дотримуйтесь інструкцій, щоб підключити доступну платіжну систему та скопіюйте наданий токен.

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

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

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

## **Як виставити рахунок клієнту**

Щоб надіслати рахунок у 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)**

<table><thead><tr><th width="270">Параметри функції</th><th>Опис параметра</th></tr></thead><tbody><tr><td><mark style="color:red;"><strong>!</strong></mark> provider_token </td><td>(обов’язковий параметр) токен, отриманий від BotFather після підключення платіжної системи</td></tr><tr><td><mark style="color:red;"><strong>!</strong></mark> platform_id </td><td>(обов’язковий параметр) ID одержувача — ідентифікатор користувача, групи або каналу</td></tr><tr><td><mark style="color:red;"><strong>!</strong></mark> title </td><td>(обов’язковий параметр) назва товару, 1–32 символи</td></tr><tr><td><mark style="color:red;"><strong>!</strong></mark> description </td><td>(обов’язковий параметр) опис товару, 1–255 символів</td></tr><tr><td><mark style="color:red;"><strong>!</strong></mark> currency </td><td>(обов’язковий параметр) валюта платежу (<mark style="color:за замовчуванням;background-color:red;"><strong>EUR</strong></mark>, USD, UAH тощо; докладніше<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>Масив масивів, що містить дані про ціни товару та додаткових послуг (доставка, пакування тощо). Відображається на сторінці оплати. Суму можна вказати як ціле число (наприклад, 125) або як десяткове число через крапку (наприклад, 120.25).
<br></p><p>Наприклад: [["product", 2000], ["VAT", 20.75], ["packaging", 100]]</p></td></tr><tr><td>photo_url</td><td>URL зображення товару</td></tr><tr><td>payload </td><td>Перша частина платіжного callback, за замовчуванням <strong>tg_payment</strong></td></tr><tr><td>protect_content</td><td>1 - захист від копіювання та скріншотів, 0 - без захисту</td></tr><tr><td>disable_notification </td><td>1 - надіслати з повідомленням, 0 - без повідомлення</td></tr><tr><td>need_name</td><td>1 - вимагати повне ім’я користувача для завершення замовлення, 0 - не запитувати ім’я</td></tr><tr><td>need_phone_number</td><td>1 - вимагати номер телефону користувача для завершення замовлення, 0 - не запитувати номер телефону</td></tr><tr><td>need_email </td><td>1 - вимагати email користувача для завершення замовлення, 0 - не запитувати email</td></tr><tr><td>reply_to_message_id</td><td>ID повідомлення, на яке потрібно відповісти; якщо ви хочете надіслати рахунок як окреме повідомлення, використовуйте дві одинарні лапки ('')</td></tr><tr><td>reply_markup</td><td>Клавіатура, у першій кнопці якої встановлено тип <strong>pay</strong></td></tr><tr><td>message_thread_id </td><td>ID теми (доступно для супергруп із увімкненою функціональністю форуму)</td></tr><tr><td>provider_data </td><td>Дані рахунку у <strong>JSON</strong> форматі, які будуть надіслані постачальнику платіжних послуг. Платіжна система повинна надати докладні описи обов’язкових полів.</td></tr></tbody></table>

{% hint style="warning" %}
**ВАЖЛИВО!** Усі параметри потрібно передавати в порядку, зазначеному у функції. Якщо вам потрібно вказати певний параметр і пропустити інші, залишайте порожні значення або значення, як зазначено в документації для параметрів, які вам не потрібні.
{% endhint %}

Приклад:

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

Якщо будь-які з параметрів `need_name`, `need_phone_number`, або `need_email` увімкнено, користувачеві буде запропоновано надати цю інформацію перед завершенням оплати. Після успішної оплати дані зберігаються у відповідних змінних клієнта.

Приклад:

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

Результат: дані запитуються перед оплатою.

## Платіжний callback

Якщо платіж успішний, у чат користувача буде надіслано callback із таким вмістом:

tg\_payment 1372995196 120.75 <mark style="color:red;">**USD**</mark> 2ff747b9-000f-5000-b000-16d7e3517aa&#x39;**,** де&#x20;

1. course\_pay - payload - payload із початкового запиту на створення рахунку;&#x20;
2. 1372995196 - ID чату, куди спочатку було надіслано рахунок;
3. 120.75 - загальна сума платежу;
4. <mark style="color:red;">**USD**</mark> - валюта;
5. 2ff747b9-000f-5000-b000-16d7e3517aa9 - ID платежу в системі продавця.

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

Крім того, якщо було запитано ім’я, номер телефону та/або email користувача, відповідні змінні буде призначено клієнту:

**tg\_payment\_name**, **tg\_payment\_phone** і **tg\_payment\_email**

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

{% hint style="info" %}
Успішний payment callback буде надіслано в **прямі повідомлення** користувачу від бота.

Користувач **повинен мати наявний чат** із ботом (тобто він має розпочати або підписатися на бота), **перед** коли здійснюється платіж. Інакше бот не зможе надіслати йому пряме повідомлення.
{% endhint %}

{% hint style="info" %}
Після отримання платіжного webhook платіж буде автоматично підтверджено через метод answerPreCheckoutQuery. <https://core.telegram.org/bots/api#answerprecheckoutquery>
{% endhint %}

## Закріплене повідомлення з кнопкою оплати

Потрібно використовувати функцію закріплення повідомлень після підключення платіжної системи.

**tg\_pin\_chat\_message(platform\_id, message\_id, disable\_notification)**

<table><thead><tr><th width="271">Параметри функції</th><th>Опис</th></tr></thead><tbody><tr><td><mark style="color:red;"><strong>!</strong></mark><strong> platform_id</strong></td><td>ID чату Telegram <a href="#gde-vzyat-platform_id-dlya-otpravki-uvedomlenii"><strong>*</strong></a></td></tr><tr><td><strong>message_id</strong> </td><td>ID повідомлення, яке потрібно закріпити</td></tr><tr><td><strong>disable_notification</strong> </td><td>Цей параметр визначає, чи потрібно надсилати сповіщення всім учасникам чату про нове закріплене повідомлення. Сповіщення завжди вимкнені в каналах і приватних чатах.
<br>Щоб вимкнути сповіщення, встановіть <strong>disable_notification</strong> параметр у 1; інакше використовуйте 0.</td></tr></tbody></table>

Приклад:

Крок 1:\
prices = \[\["course", 100], \["VAT", 20.75]]

result=tg\_send\_invoice('381764678:TEST:129736', platform\_id, 'Курс про курси', 'Створювати курси легко', '<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"}]]}')

Крок 2:\
У результаті першого кроку ви отримаєте відповідь, з якої потрібно витягнути **message\_id** значення за допомогою **get()** функції.\
res=get(result,'result')\
m\_id=get(res,'message\_id')

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

Далі закріпіть повідомлення: tg\_pin\_chat\_message(#{platform\_id}, #{m\_id}, 1)

### Приклад: мінімальний набір параметрів

prices = \[\["super course", 100]]

result= tg\_send\_invoice('381764678:TEST:129736', platform\_id, 'Курс про курси', 'Створювати курси дуже легко', '<mark style="color:red;">**USD**</mark>', prices)

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

### **Приклад: клавіатура**

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

tg\_send\_invoice('381764678:TEST:129736', platform\_id, 'Курс про курси', 'Створювати курси легко, '<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/135ec3f2c9f1e6d9c83fe4bcfcd7e87616023835" 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/doc/uk/chatbot/mesendzheri/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.