# Paypal

* [Як налаштувати Paypal ](#kak-nastroit-paypal)посилання Як налаштувати Paypal
* [Як створити посилання на оплату ](#sozdanie-ssylki-na-oplatu) посилання Як створити посилання на оплату
* [Як створити рекурентний платіж](#kak-sozdat-rekkurentnyi-platezh) посилання Як створити рекурентний платіж
* [Як обробити результат](#obrabotka-rezultata) посилання Як обробити результат

## Як налаштувати Paypal

Щоб працювати з Paypal, потрібно отримати два ключі: **client\_id** та **секретний**

Перейдіть на сторінку <https://developer.paypal.com/developer/applications/>

І виберіть зі списку або створіть новий застосунок:

![](https://lh4.googleusercontent.com/i7wtKw-RzPSHarXCkIVIqPvAvn_39t1r4CPL9lSmxzFc1mNiz24zHj4PJIUUhCzL-YXaNrQbK5edCP9bYHGXkIij59shZ6XPj3YZiVp4uRlDllvWRetnF1Y3GSbQXRZt03OOiGxs)

Угорі перемкніться в режим Live і виберіть потрібний застосунок. Відкриється сторінка налаштувань, де розміщені потрібні нам дані:<br>

![](https://lh4.googleusercontent.com/DEKr4nWXl27UVUoT4Ycl_nOx0Aj-M7KrLcgxWR-uTaUFV82416Wwd2ib4ghxQ3jiW5P53KfMwkqvB_ZS3KjLxNNdn8bzbpvVgfeV5HKsL_iFcv6bc1y_0yntseRKzwPUGz37bpnn)

Скопіюйте дані та вставте їх у відповідні поля в налаштуваннях Mavibot: перейдіть у розділ "Acquiring" і знайдіть сервіс Paypal:

<figure><img src="/files/f7290d8240d9df0f07e75cefbdae7355425f777d" alt=""><figcaption></figcaption></figure>

Далі натисніть "Connect" і заповніть поля попередньо отриманим секретним ключем і Client ID:

<figure><img src="/files/588724c48c3c24d8e17b5d0c0f5ab62d4af3a376" alt=""><figcaption></figcaption></figure>

Далі натисніть "Save settings". На цьому підключення завершено.

## Як створити посилання на оплату

### Використання змінної payment\_sum

Щоб згенерувати посилання на оплату, потрібно задати значення **payment\_sum** змінної, і одразу після цього **paypal\_pay\_url** змінна з’явиться.

| Параметри функції        | Опис параметра                                                                              | Примітка                                                                                                                     |
| ------------------------ | ------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **payment\_title**       | <p>(необов’язкова змінна)<br>це назва товару.</p>                                           | Якщо вона не вказана, заповнюється текстом: **“Invoice payment order\_id"** (order\_id — ідентифікатор замовлення в mavibot) |
| **payment\_description** | опис товару, необов’язкове поле                                                             |                                                                                                                              |
| **company\_name**        | назва вашої компанії відображається у самому верху сторінки оплати (приклад нижче, company) |                                                                                                                              |

![](https://lh4.googleusercontent.com/sVxsMZdMlVcetXrFFXEWC9lV6dNB3dzDTBWv05Cl5GiilrRWDHlAy69a_ntlX2jY3esyzOPv8TGDm-YHQwnkz1nVMlMtWL6M7rOqeJMNRs0KY22g_d50EksFL8U7y7pF2BZH6FqJ)

Крім того, перед вказанням payment\_sum можна зазначити, якою мовою буде сторінка оплати.

Для цього задайте змінну locale. Мова за замовчуванням — <mark style="color:red;">**російська (ru-RU).**</mark> Можливі варіанти: da-DK, he-IL, id-ID, ja-JP, no-NO, pt-BR, ru-RU, sv-SE, th-TH, zh-CN, zh-HK, zh-TW тощо. (набір доступних мов може відрізнятися, орієнтуйтеся на оригінальне джерело) посилання [первоисточник](https://developer.paypal.com/api/rest/reference/locale-codes/))

Також можна вказати валюту, в якій приймається платіж. Для цього вкажіть **currency** змінну, <mark style="color:red;">**рубль (RUB)**</mark> встановлено за замовчуванням, для долара задайте значення USD (currency = USD). Можливі варіанти валют можна знайти за посиланням.  [посиланні](https://developer.paypal.com/docs/api/reference/currency-codes/).&#x20;

А третій додатковий параметр — це **company\_name** — назва вашої компанії, що відображається у самому верху сторінки оплати (приклад нижче, company)

Поле **paypal\_pay\_url** змінна може відображатися як посилання або бути розміщена на кнопці з текстом "Pay".

Посилання має такий вигляд: [https://www.paypal.com/checkoutnow?token=07N53571YM296381N](https://www.sandbox.paypal.com/checkoutnow?token=07N53571YM296381N)

Приклад реалізації.

Встановлення суми платежу та назви компанії

<figure><img src="/files/732728d7b913440044bdf8f478a4d943cfe19256" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
&#x20;**Зверніть увагу:** кнопкою **payment\_sum** змінній присвоюється останнє значення, після необов’язкових змінних **payment\_title, company\_name,** тощо.
{% endhint %}

Далі вкажіть змінну #**{paypal\_pay\_url}** у другому блоці "Status":

1. Змінну можна вказати в полі message:

<figure><img src="/files/fabd2ab88658e525822e54ff014d6e56b3397967" alt=""><figcaption></figcaption></figure>

2. Змінну можна вказати в полі url у налаштуваннях вкладення:

<figure><img src="/files/8735272713a0c9d32f2ac22375ab84553a693088" alt=""><figcaption></figcaption></figure>

3. Змінну можна вказати в полі url у налаштуваннях кнопки:

<figure><img src="/files/30929b5c3d2dd497424388b8e9a0ce45afcfbbac" alt=""><figcaption></figcaption></figure>

Під час відкриття посилання на оплату

![](https://lh3.googleusercontent.com/GvWy17AiTcE0apTWzoPjoADq9h9bXWMRjS61DC00iwnVfSojYKvGS6Puhr6Eg0KfBtBnUza1rY_Mlh0351ka2ikbmNkC6-9zjc2CP-LdUYOQjX4fMaB3V-AT9IRTrMbqRxD-KzW2)

### Використання функції калькулятора paypal\_payment\_url

Створіть блок конструктора воронки та використайте **paypal\_payment\_url** функцію в калькуляторі, передавши їй потрібні параметри:

<table><thead><tr><th width="264">Параметри функції</th><th>Опис параметра</th></tr></thead><tbody><tr><td><mark style="color:red;"><strong>!</strong></mark> <strong>payment_sum</strong></td><td>обов’язковий параметр — сума платежу.</td></tr><tr><td><strong>currency</strong></td><td> Валюта платежу за замовчуванням — ‘USD'. Повний список доступний за посиланням <a href="https://developer.paypal.com/docs/api/reference/currency-codes/">https://developer.paypal.com/docs/api/reference/currency-codes/</a></td></tr><tr><td><strong>payment_title</strong></td><td>заголовок платежу (до 127 символів). (Якщо не вказано, заповнюється текстом: “Invoice payment payment_id”, де payment_id — ID замовлення в Mavibot)</td></tr><tr><td><strong>payment_description</strong></td><td>короткий опис платежу<br>(<em>до 127 символів</em>)</td></tr><tr><td>company_name</td><td>необов’язковий параметр, назва організації/компанії тощо.</td></tr><tr><td><strong>locale</strong></td><td>Мова сторінки оплати вказується як en-US, fr-XC тощо.<br>За замовчуванням — ‘ru-Ru’.<br>Повний список доступний за посиланням https://developer.paypal.com/api/rest/reference/locale-codes/</td></tr></tbody></table>

Коли умова блоку виконується, клієнт отримає посилання на оплату, і **paypal\_payment\_completed** у клієнта буде створено змінну зі значенням <mark style="color:red;">**False.**</mark>

<figure><img src="/files/b35b5cc38e0dd3043d4fde781c8c7c2365d10b9b" alt="" width="563"><figcaption></figcaption></figure>

`url = paypal_payment_url(2500,`` `<mark style="color:red;">`'RUB'`</mark>`, 'Invoice payment payment_id','payment description', 'organization name', 'ru-Ru')`

## Як створити рекурентний платіж

Щоб створити та отримати посилання на оплату з рекурентними платежами, потрібно створити **план підписки** в особистому кабінеті.&#x20;

<figure><img src="/files/790936d596cf02b333cae18c89778ba51888b569" alt="" width="548"><figcaption></figcaption></figure>

<figure><img src="/files/ea3de3e8be9161e4e8294413e391cbba1ccedeac" alt="" width="563"><figcaption></figcaption></figure>

Вибір уже створеної пропозиції:

<figure><img src="/files/6659cc4559b2bddfa1dc88168b31ccee979c2d0e" alt="" width="563"><figcaption></figcaption></figure>

Або введіть назву пропозиції в рядок пошуку та натисніть "Create".

<figure><img src="/files/4388d8de1f2084c169ef43eae0168b9519cc6e61" alt="" width="563"><figcaption></figcaption></figure>

<figure><img src="/files/9835d45248f4b0880ee6f004306ff961d85ee8ba" alt="" width="563"><figcaption><p>Створення пропозиції підписки в paypal</p></figcaption></figure>

Виберіть тип автосписання Fixed:

<figure><img src="/files/094c47b04f1c412d76b36e87c49367eaed0b6b5d" alt="" width="563"><figcaption></figcaption></figure>

Створити підписку

<figure><img src="/files/5939c4fe3042834f301c0beb785c7594110383d9" alt="" width="563"><figcaption></figcaption></figure>

Вибір валюти підписки та умов списання:

{% hint style="danger" %} <mark style="color:red;">**Увага!!**</mark>&#x20;

У Mavibot валюта за замовчуванням — євро, якщо списання відбувається в доларах або в іншій валюті, то під час створення підписки вкажіть потрібну валюту, а в Mavibot — ту саму валюту з підписки Paypal.
{% endhint %}

<figure><img src="/files/a68b7e85fcf861193d9b8f94b254fb109c499f11" alt="" width="563"><figcaption></figcaption></figure>

Далі активуйте підписку:

<figure><img src="/files/0796ed14a63c23a20bf8be149becdd03d7befbf5" alt="" width="563"><figcaption></figcaption></figure>

<figure><img src="/files/e3260b47d7f477b08058acfc5bbfa7634dbb7993" alt="" width="563"><figcaption></figcaption></figure>

Після створення буде доступний її ID, який ми будемо використовувати надалі для створення підписки та отримання посилання на оплату.

<figure><img src="/files/27f918568c310308a7bd62f4039747575bac4075" alt="" width="563"><figcaption></figcaption></figure>

Посилання на оплату генерується та повертається функцією:\
**paypal\_subscription\_url(plan\_id, shipping\_currency, shipping\_payment\_sum, start\_time)**&#x20;

| Параметри функції                                            | Опис параметра                                                                                                                                                                                                                                 |
| ------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| <mark style="color:red;">**!**</mark> **plan\_id**           | ID плану підписки                                                                                                                                                                                                                              |
| <mark style="color:red;">**!**</mark> **shipping\_currency** | якщо оплата для вказаного плану у доларах, то нічого передавати не потрібно, інакше передаємо код валюти, який ви вказали в плані. Тут передається валюта, в якій оплачується доставка (навіть якщо її вартість нульова). За замовчуванням USD |
| **shipping\_payment\_sum**                                   | це необов’язковий параметр, який вказує вартість доставки. За замовчуванням значення дорівнює нулю.                                                                                                                                            |
| **start\_time**                                              | <p>необов’язковий параметр, дата й час початку підписки. Якщо нічого не передавати, то дата початку підписки = дата платежу.<br> Формати: %d.%m.%Y або %d.%m.%Y %H:%M. </p>                                                                    |

<figure><img src="/files/86b5cfb3216b6f14f0714338b8d8a968a6ececa4" alt="" width="563"><figcaption></figcaption></figure>

Під час створення посилання **paypal\_subscription\_id** також з’явиться змінна, яка міститиме ID підписки.

Під час оплати ви отримаєте callback, який аналогічний оплаті звичайного платежу.

**paypal\_subscription\_data(paypal\_subscription\_id)** — отримання інформації про підписку

| Параметри функції            | Опис параметрів |
| ---------------------------- | --------------- |
| **paypal\_subscription\_id** | ID підписки.    |

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

### Як скасувати підписку

Функція paypal\_remove\_subscription(paypal\_subscription\_id) допоможе клієнтам скасувати підписку на ваші послуги.

Параметри:

| Параметри функції        | Опис                                                                          |
| ------------------------ | ----------------------------------------------------------------------------- |
| paypal\_subscription\_id | ID підписки, який зберігається в змінній клієнта під час оформлення підписки. |

<figure><img src="/files/a8e9eecbba1be8faabf994a3d6c9c807c2c213e3" alt=""><figcaption></figcaption></figure>

## Як обробити результат

{% hint style="info" %}
Після успішного платежу в бот надсилатимуться callback-и, які повідомлять, що платіж успішний.
{% endhint %}

{% hint style="success" %}
У системі ви бачите callback-и як повідомлення від користувача, але сам користувач ЇХ НЕ БАЧИТЬ: вони відображаються лише оператору.
{% endhint %}

{% hint style="danger" %}
Щоб обробити callback у блоці та надіслати користувачу повідомлення про статус платежу, використовуйте тип порівняння "Exact match".
{% endhint %}

{% hint style="warning" %}
Callback-и можуть надходити із затримкою, тому після показу користувачеві посилання на оплату рекомендується надіслати повідомлення на кшталт: “Після здійснення оплати, будь ласка, дочекайтеся повідомлення про підтвердження успішної оплати.”
{% endhint %}

### Для прямого платежу

Callback успішної оплати складається з перших 10 символів secret та підпису зі статусом. Наприклад: EHsWHYOoWV\_success

Приклад 1: реакція на успішний платіж за допомогою блоку "Start condition":

<figure><img src="/files/8e98855a09911d88d4d2c166c96e0e503a557c6f" alt=""><figcaption></figcaption></figure>

Приклад 2: реакція на успішний платіж за допомогою блоку "Start condition":

<figure><img src="/files/94a1295c9a3907552382382b710c230b54ae269b" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
Якщо ви не хочете виводити користувача з основного потоку чатбота, використовуйте блок “No-state with condition” — користувачів не можна перенаправити в цей блок напряму, тож після успішної оплати вони залишаться в основній воронці, а також отримають сповіщення про успішну оплату.

Але якщо ви хочете продовжити воронку на основі події успішної оплати, використовуйте блок “Start condition”. У цьому випадку після завершення блоку оплати користувач буде перенаправлений у блок “Start condition”, з якого можна продовжити побудову воронки.
{% endhint %}

{% hint style="info" %}
Більше інформації про умовні блоки наведено в однойменній статті. [у блоках з умовою розповіли](broken://pages/ef6045e9c695451c2362686c7e0d9065d63b1634) посилання
{% endhint %}

Після успішної оплати змінна paypal\_payment\_completed встановлюється в True.

Після завершення оплати клієнту додається змінна paypal\_callback\_data, яка містить актуальні дані платіжної системи про статус транзакції. Ви можете отримати потрібні дані з отриманого словника за допомогою методу get.

{% hint style="danger" %}
Щоб здійснити повторний платіж, потрібно скинути змінну payment\_sum, змінну з раніше згенерованим посиланням, а потім знову присвоїти змінну payment\_sum або викликати функцію для отримання нового посилання.
{% endhint %}

### Для платежів за підпискою

{% hint style="danger" %}
Функцію налаштування callback-ів для операцій, пов’язаних із підпискою, додано 09/01/2024. Щоб callback-и цієї категорії працювали коректно, потрібно вимкнути та повторно підключити інтеграцію платіжної системи Paypal у вашому проєкті.
{% endhint %}

Під час оплати підписки бот отримає одне з таких повідомлень:

* про активацію підписки. Наприклад, subscription\_I-PTV5H4MRC1H3\_activated;
* Сповіщення про успішний повторюваний платіж за підпискою. Наприклад, subscription\_I-PTV5H4MRC1H3\_paid;
* або про помилку оплати підписки. Наприклад, subscription\_I-PTV5H4MRC1H3\_not\_paid;

У наведених вище прикладах “I-PTV5H4MRC1H3” — це ID підписки клієнта, до якого можна звернутися за допомогою змінної paypal\_subscription\_id.

Callback додасть клієнту змінну paypal\_subscription\_callback\_data, яка містить актуальні дані платіжної системи про статус транзакції. Ви можете отримати потрібні дані з отриманого словника за допомогою методу get.

Приклад 1: реакція на активацію підписки за допомогою блоку "Start condition":

<figure><img src="/files/02587a2a48217e3a52bbad824630c43fbe005edb" alt=""><figcaption></figcaption></figure>

Приклад 1: Реакція на активацію підписки за допомогою блоку "Not state with condition":&#x20;

<figure><img src="/files/75a1c519ef747e1e3955dc27ac487c659029d0ae" alt=""><figcaption></figcaption></figure>


---

# 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/oplata/paypal.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.