# Paypal

* [كيف تُعدّ Paypal ](#kak-nastroit-paypal)رابط How to set up Paypal
* [كيف تنشئ رابطًا للدفع ](#sozdanie-ssylki-na-oplatu) رابط How to create a payment link
* [كيف تنشئ دفعة متكررة](#kak-sozdat-rekkurentnyi-platezh) رابط How to create a recurring payment
* [كيفية معالجة النتيجة](#obrabotka-rezultata) رابط  How to process the result

## How to set up Paypal

للعمل مع Paypal، تحتاج إلى الحصول على مفتاحين: **client\_id** و **secret**

اذهب إلى الصفحة <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/185636d39814bd5cb0d5f65c6dd4136826dc8888" alt=""><figcaption></figcaption></figure>

بعد ذلك، انقر على "Connect" واملأ الحقول بالمفتاح السري وClient ID اللذين حصلت عليهما مسبقًا:

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

بعد ذلك، انقر على "Save settings". وبذلك يكتمل الاتصال.

## How to create a payment link

### Using payment\_sum variable

لإنشاء رابط دفع، تحتاج إلى تعيين قيمة **payment\_sum** المتغير وبعد ذلك مباشرةً سيظهر المتغير **paypal\_pay\_url** .

| معلمات الدالة            | وصف المعلمة                                                     | ملاحظة                                                                                                  |
| ------------------------ | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| **payment\_title**       | <p>(متغير اختياري)<br>هذا هو اسم المنتج.</p>                    | إذا لم يتم تحديده، فسيُملأ بالنص: **“Invoice payment order\_id"** (order\_id هو معرّف الطلب في mavibot) |
| **payment\_description** | وصف المنتج، حقل اختياري                                         |                                                                                                         |
| **company\_name**        | يظهر اسم شركتك في أعلى صفحة الدفع تمامًا (المثال أدناه، الشركة) |                                                                                                         |

![](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/6812a2b6cf2fb6cbdcd204bc930a7400e61ef49a" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
&#x20;**يرجى الملاحظة:** الـ **payment\_sum** يُعيَّن المتغير بالقيمة الأخيرة، بعد المتغيرات الاختيارية **payment\_title, company\_name,** إلخ.
{% endhint %}

بعد ذلك، حدّد المتغير #**{paypal\_pay\_url}** في كتلة "Status" الثانية:

1. يمكن تحديد المتغير في حقل الرسالة:

<figure><img src="/files/568f7ef6d079049fe093431fa9d6183d6ffb8c1f" alt=""><figcaption></figcaption></figure>

2. يمكن تحديد المتغير في حقل url في إعدادات المرفق:

<figure><img src="/files/7d5cdebbd1053070f1d67d357743c91cc0b4e889" alt=""><figcaption></figcaption></figure>

3. يمكن تحديد المتغير في حقل url في إعدادات الزر:

<figure><img src="/files/736f96c39711bacecec0613faf3a8a063acd0eaa" 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 هو معرّف الطلب في 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/beaba5d48cc97214a17483775fb2046f1fee68a0" 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')`

## How to create a recurring payment

لإنشاء والحصول على رابط للدفع عبر المدفوعات المتكررة، تحتاج إلى إنشاء **خطة اشتراك** في حسابك الشخصي.&#x20;

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

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

اختيار العرض الذي تم إنشاؤه مسبقًا:

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

بديلًا عن ذلك، اكتب اسم العرض في شريط البحث وانقر على "Create".

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

<figure><img src="/files/63232ec834c200054bbc497f62350916d285e958" alt="" width="563"><figcaption><p>Creating a subscription offer in paypal</p></figcaption></figure>

اختر نوع الخصم التلقائي Fixed:

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

Create subscription

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

اختيار عملة الاشتراك وشروط الخصم:

{% hint style="danger" %} <mark style="color:red;">**تنبيه!!**</mark>&#x20;

في Mavibot، العملة الافتراضية هي اليورو، وإذا كان الخصم بالدولار أو بعملة أخرى، فعند إنشاء الاشتراك حدّد العملة التي تحتاجها، وفي Mavibot نفس العملة من اشتراك Paypal.
{% endhint %}

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

بعد ذلك، فعّل الاشتراك:

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

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

بعد الإنشاء، سيكون معرّفه متاحًا، وسنستخدمه لاحقًا لإنشاء اشتراك والحصول على رابط دفع.

<figure><img src="/files/fb06e620198dbc11299740a883463fc99a7e1c54" 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**           | معرّف خطة الاشتراك                                                                                                                                                                                      |
| <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/fcf120c62d1fd09ced3a2de1c0c9c1a2384ce5dc" alt="" width="563"><figcaption></figcaption></figure>

عند إنشاء الرابط، سيظهر أيضًا المتغير **paypal\_subscription\_id** ، والذي سيحتوي على معرّف الاشتراك.

أثناء الدفع، ستتلقى callback، وهو مشابه للدفع مقابل عملية دفع عادية.

**paypal\_subscription\_data(paypal\_subscription\_id)** - الحصول على معلومات عن الاشتراك

| معلمات الدالة                | وصف المعلمات    |
| ---------------------------- | --------------- |
| **paypal\_subscription\_id** | معرّف الاشتراك. |

الـ **النتيجة** لتنفيذ الدالة - هي مصفوفة تحتوي على جميع معلومات الاشتراك، بما في ذلك عدد الدفعات، وعدد محاولات الخصم الفاشلة، والحالة، والمزيد.

### How to cancel subcription

ستساعد الدالة paypal\_remove\_subscription(paypal\_subscription\_id) العملاء على إلغاء اشتراكاتهم في خدماتك.

المعلمات:

| معلمات الدالة            | الوصف                                                      |
| ------------------------ | ---------------------------------------------------------- |
| paypal\_subscription\_id | معرّف الاشتراك الذي يتم حفظه في متغير العميل عند الاشتراك. |

<figure><img src="/files/55425452a044427c3f8ba33a31c9db3086f41583" alt=""><figcaption></figcaption></figure>

## كيفية معالجة النتيجة

{% hint style="info" %}
بعد نجاح الدفع، سيتم إرسال callbacks إلى البوت، مما سيتيح لك معرفة أن الدفع كان ناجحًا.
{% endhint %}

{% hint style="success" %}
في النظام، ترى callbacks على أنها رسائل من المستخدم، لكن المستخدم نفسه لا يراها: فهي تُعرض للمشغل فقط.
{% endhint %}

{% hint style="danger" %}
لمعالجة callback في الكتلة وإرسال رسائل للمستخدم عن حالة الدفع، استخدم نوع المقارنة "Exact match".
{% endhint %}

{% hint style="warning" %}
قد تتأخر callbacks، لذلك بعد عرض رابط الدفع للمستخدم، يُنصح بإرسال رسالة مثل: “بعد إتمام الدفع، يرجى الانتظار حتى تصلك رسالة تأكيد تفيد بأن الدفع تم بنجاح.”
{% endhint %}

### For direct payment

تتكون callback الخاصة بالدفع الناجح من أول 10 أحرف من secret والتوقيع مع الحالة. على سبيل المثال: EHsWHYOoWV\_success

المثال 1: التفاعل مع دفع ناجح باستخدام كتلة "Start condition":

<figure><img src="/files/63e7113ebb7f92ff5fb770d0208f8a7f61229658" alt=""><figcaption></figcaption></figure>

المثال 2: التفاعل مع دفع ناجح باستخدام كتلة "Start condition":

<figure><img src="/files/76d1488f5d808f0276c475fef0efb5d7ad94405a" alt=""><figcaption></figcaption></figure>

{% hint style="info" %}
إذا كنت لا تريد إخراج المستخدم من تدفق الشات بوت الرئيسي، فاستخدم كتلة “No-state with condition” — لا يمكن إعادة توجيه المستخدمين إلى هذه الكتلة مباشرةً، لذا بعد الدفع الناجح سيبقون مع ذلك في القمع الرئيسي، مع تلقي إشعار بالدفع الناجح أيضًا.

ولكن إذا كنت تريد متابعة القمع بناءً على حدث الدفع الناجح، فاستخدم كتلة “Start condition”. في هذه الحالة، بعد إكمال كتلة الدفع، سيتم تحويل المستخدم إلى كتلة “Start condition”، والتي يمكنك من خلالها مواصلة بناء القمع الخاص بك.
{% endhint %}

{% hint style="info" %}
تتوفر معلومات إضافية عن الكتل الشرطية في المقالة التي تحمل الاسم نفسه. [блоках с условием рассказали](broken://pages/fbd5b316dbf191d7c4928912a5ac514468d6432a) رابط
{% endhint %}

عند نجاح الدفع، يتم تعيين المتغير paypal\_payment\_completed إلى True.

بعد اكتمال الدفع، تتم إضافة المتغير paypal\_callback\_data إلى العميل، والذي يحتوي على بيانات محدثة لنظام الدفع حول حالة العملية. يمكنك استخراج البيانات اللازمة من القاموس المستلم باستخدام طريقة get.

{% hint style="danger" %}
لإجراء دفعة متكررة، تحتاج إلى إعادة تعيين المتغير payment\_sum، والمتغير الذي يحتوي على الرابط المُنشأ مسبقًا، ثم إعادة تعيين المتغير payment\_sum أو استدعاء الدالة للحصول على رابط جديد.
{% endhint %}

### For subscription payments

{% hint style="danger" %}
تمت إضافة دالة إعداد callback للعمليات المتعلقة بالاشتراكات في 09/01/2024. ولكي تعمل callbacks من هذه الفئة بشكل صحيح، تحتاج إلى تعطيل وربط تكامل نظام دفع Paypal في مشروعك.
{% endhint %}

عند إجراء دفعة اشتراك، سيتلقى البوت إحدى الرسائل التالية:

* حول تفعيل الاشتراك. على سبيل المثال، subscription\_I-PTV5H4MRC1H3\_activated;
* إشعار بنجاح دفعة اشتراك متكررة. على سبيل المثال، subscription\_I-PTV5H4MRC1H3\_paid;
* أو حول خطأ في دفع الاشتراك. على سبيل المثال،  subscription\_I-PTV5H4MRC1H3\_not\_paid;

في الأمثلة أعلاه، “I-PTV5H4MRC1H3” هو معرّف اشتراك العميل، والذي يمكن الوصول إليه باستخدام متغير paypal\_subscription\_id.

ستضيف callback المتغير paypal\_subscription\_callback\_data إلى العميل، والذي يحتوي على بيانات حالية لنظام الدفع حول حالة العملية. يمكنك استخراج البيانات اللازمة من القاموس المستلم باستخدام طريقة get.

المثال 1: التفاعل مع تفعيل الاشتراك باستخدام كتلة "Start condition":

<figure><img src="/files/2dd0a5aaf9d9ff6566f355eaf94eb3118c9747af" alt=""><figcaption></figcaption></figure>

المثال 1: التفاعل مع تفعيل الاشتراك باستخدام كتلة "Not state with condition":

<figure><img src="/files/9f1607c4d6120e2576a1227c2a0e280e3ffedb5e" 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/ar/aldfa/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.