# Stripe ## كيفية الربط لتوصيل نظام الدفع Stripe، ستحتاج إلى مفتاح API سري ومفتاح webhook. يمكنك نسخ مفتاح API السري بالانتقال إلى قسم Developers -> API key ونسخ المفتاح السري. الخطوة 1. انتقل إلى قسم Developers -> API key:

الخطوة 2. اعثر على المفتاح السري وانسخه:

بعد ذلك، تحتاج إلى تعيين عنوان URL لعمليات رد النداء. هذا ضروري لكي يتمكن البوت من تلقي إشعارات الدفع. انتقل إلى قسم Webhooks وأضف العنوان الخاص بـ webhooks.

يتم فتح النموذج:

الخطوة 1. انقر على "+add destination". الخطوة 2. حدّد الأحداث:

الخطوة 3. حدّد نوع "Webhook endpoint":

الخطوة 4. نتعرف على نوع الطلب وننقر على "Continue":

الخطوة 5. نكتب الاسم ونحدد عنوان URL لنقطة النهاية:

حدد عنوان URL - الخطوة 6. سيتم إنشاء نقطتي نهاية، ويمكنك عرض الإعدادات قبل الإضافة:

الخطوة 7. بعد ذلك، انقر على زر "Add destinations". ثم سيتم حفظ الـ webhooks. الخطوة 8. انقر على زر "Done".

نحفظه وننتقل إلى الصفحة التي تحتوي على webhook المثبّت:

الخطوة 9. بعد ذلك، انقر على webhook الذي حددت فيه جميع الأحداث:

الخطوة 10. نعثر على Signig key ونحفظه لدينا (سنحتاجه لاحقًا للاتصال بـ Salebot):

بعد استلام المفاتيح، ننتقل إلى الاتصال بـ Mavibot. في Mavibot، افتح قسم "Acquiring" واختر Stripe.

في صفحة الاتصال، تحتاج إلى إدخال المفاتيح المستلمة:

انقر على "Save Settings". {% hint style="success" %} تم! بهذا يكتمل توصيل نظام الدفع! {% endhint %} ## كيفية توصيل رد نداء بشأن حالة المعاملة للحصول على رد نداء إضافي، سنحتاج إلى توصيل webhook في **إضافةً إلى الموجود بالفعل.** حدد عنوان URL - [https://chatter.salebot.pro/stripe\_callback/\/charge\_status](https://chatter.salebot.pro/stripe_callback//charge_status) وتحديد الأحداث: * `charge.failed` * `charge.pending` * `charge.succeeded`

{% hint style="success" %} **تعرّف أكثر على كل نوع من أنواع webhook:** 1. **charge.succeeded** - يحتوي على معلومات حول إتمام المعاملة بنجاح (مشابه لرد نداء حول الدفع الناجح) 2. **charge.pending** - "المعاملة قيد التنفيذ"، وقد يستغرق إكمالها حتى 7 أيام.\ سيبدو الـ webhook بالشكل {أول 10 أحرف }{نوع الـ webhook}\ *على سبيل المثال*: *sk\_test\_45LDPJLKT95d\_charge.pending* 3. **charge.failed** *-* "فشلت المعاملة."\ سيبدو الـ webhook بالشكل {أول 10 أحرف }{نوع الـ webhook}\ على سبيل المثال: *sk\_test\_45LDPJLKT95d\_charge.failed* {% endhint %} نضيف الـ webhook الذي تم استلامه بعد الحفظ إلى حقل Mavibot - Webhook key2:

**stripe\_invoice\_id** - معرّف المعاملة الذي لم يتم استلام رد نداء الدفع الناجح له مباشرة بعد الدفع. ## كيفية توصيل الضرائب لاستخدام الضرائب في المدفوعات، تحتاج أولاً إلى إنشائها في الحساب الشخصي لـ Stripe. للقيام بذلك، أدخل معدلات الضرائب في شريط البحث:

وانقر على "+ Add tax rates":

بعد ذلك، حدّد معدل الضريبة المطبق:

في القائمة المفتوحة، حدّد نوع الضريبة والمنطقة التي تنطبق عليها ومعدل الضريبة وخيار ما إذا كان يجب تضمين هذه الضريبة في مبلغ الدفع 'Inclusive' أو إضافتها فوق المبلغ - exclusive:

بعد إنشاء معدل الضريبة، انسخ معرّفه إلى **stripe\_tax\_id** المتغير قبل تعيين مبلغ الدفع.

لتجنب الأخطاء، ضع سلسلة فارغة ("") في المتغير stripe\_tax\_id بعد استلام الرابط، حتى تتمكن من تطبيق الضريبة فقط عند الحاجة. إذا تم كل شيء بشكل صحيح، ففي حالة معدل الضريبة ذي المعامل exclusive، سترى ما يلي

## **كيفية الحصول على رابط الدفع** لإنشاء رابط دفع، تحتاج إلى تعيين قيمة **payment\_sum** المتغير (على سبيل المثال، 150 أو 100.55 (مفصولان بنقطة!))، وسيظهر المتغير stripe\_pay\_url بعد ذلك. يمكن عرض هذا المتغير كرابط أو وضعه على زر بالنص "Pay". يبدو الرابط كما يلي: `https://checkout.stripe.com/pay/cs_test_a17mskKFFRwEuo3WgBSAUjfk7xaZZIrct9B3Ds2AdODVq1I8aRiqYEBdrU#fidkdWxOYHwnPyd1blpxYHZxWjA0TGFsVzFPVmpmMzJAbVYzUkp1Y0lLYDVgfzR2Q0NxcWZBNUNnTnRSVVRJSGFobEB1UExSczRMMTc8PWRLMGBddl8xalxyPDRoUGhnZm9xXXZANDZyaF0wNTVBVExsPHZyfycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl` {% hint style="warning" %} افتراضيًا، يتم تعيين USD (الدولار)، وإذا كنت بحاجة إلى عملة أخرى، فيجب تعيين قيمة **currency** . {% endhint %} كذلك، قبل تعيين قيمة **payment\_sum** المتغير، يمكنك تعيين المتغيرات الاختيارية التالية لتكوين الدفع.

معلمات الدالة	وصف المعلمات
currency	هي عملة الطلب. القيم المقبولة -https://stripe.com/docs/currencies
payment_description	وصف الطلب
stripe_tax_id	هذا هو معرّف معدل الضريبة، الذي تم إعداده في الحساب الشخصي لـ Stripe. تم وصف كيفية إعداده في قسم "كيفية إعداد الضرائب" الرابط "كيفية توصيل الضرائب"
stripe_invoice_enable	يشير هذا المعامل إلى ضرورة حفظ الفواتير (الفواتير، الإيصالات). أدخل أي قيمة — وستكون جميع المستندات الضرورية متاحة بعد ذلك في حسابك الشخصي في Stripe.
stripe_locale	يضبط لغة رابط الدفع: en، ru، de. جميع اللغات المتاحة موجودة هنا: https://stripe.com/docs/api/checkout/sessions/create#create_checkout_session-locale إذا كان stripe_local إذا لم يتم توفير القيمة، فسيتم استخدام لغة متصفح العميل افتراضيًا.
stripe_payment_method_type	هي طريقة الدفع، وطريقة الدفع الافتراضية هي البطاقة. يمكنك استبدالها بطرق دفع أخرى متاحة في Stripe. الطرق المتاحة مدرجة أدناه على سبيل المثال، `stripe_payment_method_type = "customer_balance"`
stripe_additional_payment_method_type	يُستخدم لإضافة طريقة دفع إضافية. الطرق المتاحة مدرجة أدناه، على سبيل المثال، `stripe_additional_payment_method_type = "sepa_debit"`
coupon_id	معرّف قسيمة الخصم
stripe_expired	هو مدة صلاحية رابط الدفع. يُحدد بالثواني. الحد الأدنى 30 دقيقة، والحد الأقصى 24 ساعة. القيمة الافتراضية 24 ساعة
stripe_automatic_tax	تمكين حساب الضرائب وتحصيلها تلقائيًا أثناء الدفع. لتمكينه، مرّر "1". يمكن العثور على معلومات مفصلة حول هذا الإعداد في وثائق Stripe. الرابط في وثائق Stripe

{% hint style="warning" %} انتباه! إذا كنت تستخدم كِلا ***stripe\_payment\_method\_type** و **stripe\_additional\_payment\_method\_type*** المتغيرات***، فيجب أن تكون القيم فيهما مختلفة!*** {% endhint %}

قائمة القيم لـ stripe_payment_method_type و stripe_additional_payment_method_type

card\ acss\_debit\ affirm \ afterpay\_clearpay \ alipay\ au\_becs\_debit \ bacs\_debit \ bancontact \ blik \ boleto \ cashapp \ customer\_balance \ eps \ fpx \ giropay \ grabpay \ ideal \ klarna \ konbini \ link \ oxxo \ p24 \ paynow \ paypal \ pix \ promptpay \ sepa\_debit \ sofort \ us\_bank\_account \ wechat\_pay zip

يمكنك معرفة المزيد عن كل طريقة ولأي البلدان هي متاحة في وثائق Stripe: [عرض على الموقع ](https://stripe.com/docs/api/payment_methods/object#payment_method_object-type) ### **مثال على إنشاء رابط الدفع** لننشئ رابط دفع بقيمة 1000 روبل (الافتراضي هو الدولار)

{% hint style="warning" %} **انتبه:** \ \- أولاً تحدد المعلمات الاختيارية **first\_name, payment\_description** وهكذا.\ \- وأخيرًا نُسند قيمة إلى المتغير **payment\_sum** يمكن تعيين المتغيرات أيضًا في وقت سابق ضمن السلسلة، وليس في كتلة واحدة، هذا مجرد مثال. {% endhint %} بعد ذلك، في المكان المطلوب نعرض المتغير **stripe\_pay\_url**، والذي يحتوي على الرابط داخل الكتلة أو في الزر: مثال 1. نعرض رابط الدفع مباشرة في الرسالة:

الاختبار في البوت:

مثال 2. نضيف رابط الدفع إلى زر:

مثال 3. نضيف الرابط كمرفق إلى الرسالة:

الاختبار في البوت:

{% hint style="success" %} جميع الخيارات الثلاثة مقبولة لإرسال رابط الدفع في البوت. {% endhint %} عند النقر على الزر أو الانتقال عبر الرابط، سيتم إعادة توجيه الدافع إلى صفحة الدفع:

في المثال، يتضح أن المعلمات التي أشرنا إليها في الآلة الحاسبة ضمن إعدادات الكتلة قد تم تطبيقها: وصف الطلب، العملة، والمبلغ. إذا قمت بتمرير معلمة معدل الضريبة (**stripe\_tax\_id)** في الكتلة:

فسيتم أيضًا عرض معدل الضريبة في نموذج الدفع:

مثال على كود للنسخ

`payment_description = 'دفعة اختبارية في Stripe'` \ `currency = 'RUB'` \ `stripe_tax_id = 'انسخ هنا معرّف الضريبة الخاص بك tax ID'` \ `payment_sum = 1000` أين تجد tax ID:

## **كيفية إعداد المدفوعات المتكررة** بالنسبة للمدفوعات المتكررة (الاشتراكات)، يجب قبل تعريف المتغير **payment\_sum** تعريف المتغير **stripe\_subscription** وإسناد اسم الاشتراك إليه. يمكن أيضًا إضافة المتغيرات التالية: \ **interval** – مدة فترة الاشتراك، ويجب تمرير القيمة التالية إلى هذا المتغير **‘day’** - للأيام، **‘week’** - للأسابيع، **‘month’** - للأشهر، **‘year’** - للسنوات. \ إذا لم يتم تعريف المتغير، فسيتم ***افتراضيًا*** تمرير المعامل **‘month’.** {% hint style="warning" %} **مهم!** لا يمكن أن تتجاوز مدة دورة اشتراك واحدة سنة واحدة (للمعامل ‘year’)، أو 12 شهرًا (للمعامل ‘month’)، أو 52 أسبوعًا (للمعامل ‘week’). {% endhint %}

**interval\_count** – عدد الفترات المحددة، أي عدد الأيام أو الأسابيع أو الأشهر التي ستكون في الاشتراك مقابل المبلغ المحدد. ***افتراضيًا*** سيتم تمرير معامل يساوي واحدًا (**1**); **stripe\_payment\_method\_type** - طريقة الدفع، والافتراضي هو الدفع بالبطاقة (card). يمكن استبدالها بطرق دفع أخرى متاحة في Stripe. الطرق المتاحة مذكورة أدناه. على سبيل المثال، `stripe_payment_method_type = 'customer_balance'` **stripe\_additional\_payment\_method\_type** - إضافة طريقة دفع إضافية. الطرق المتاحة مذكورة أدناه على سبيل المثال، `stripe_additional_payment_method_type = 'sepa_debit'` {% hint style="warning" %} مهم! إذا كنت تستخدم كلا المتغيرين ***stripe\_payment\_method\_type** و **stripe\_additional\_payment\_method\_type، فيجب أن تكون القيم فيهما مختلفة بالضرورة!*** {% endhint %}

قائمة القيم لـ stripe_payment_method_type و stripe_additional_payment_method_type:

{% hint style="info" %} لمزيد من المعلومات حول كل طريقة والبلدان التي تتوفر فيها، راجع وثائق Stripe: انظر الموقع الرابط [عرض على الموقع ](https://stripe.com/docs/api/payment_methods/object#payment_method_object-type) {% endhint %} {% hint style="warning" %} **انتباه!** لا يمكن أن تتجاوز مدة الاشتراك سنة واحدة (للمعامل ‘year’)، أو 12 شهرًا (للمعامل ‘month’)، أو 52 أسبوعًا (للمعامل ‘week’). {% endhint %} في هذا المثال، سيتم إنشاء اشتراك باسم 'My\_subscription' بسعر 90 دولارًا أمريكيًا لمدة 3 أشهر، وسيتم إجراء دفعة متكررة بنفس المبلغ بعد هذا الشهر الواحد:

مثال للنسخ: `stripe_subscription = 'My_subscription'` \ `interval = 'month'` \ `interval_count = 3` \ `payment_sum = 90` بعد الدفع، سيكون لدى العميل **stripe\_subscription\_id** متغيرات في متغيرات الصفقة، والتي ستكون مطلوبة لإعداد إلغاء الاشتراك، و **stripe\_customer\_id**، والذي يمكن استخدامه لاحقًا للتحقق من حالة الاشتراك. {% hint style="warning" %} يتم استلام الإشعار (callback) فقط عند أول دفعة متكررة! لن يكون هناك callback للمدفوعات المتكررة اللاحقة. يتم التحكم عبر الدالة و stripe\_customer\_id. [عبر الدالة](#proverka-statusa-podpiski) رابط {% endhint %}

### العودة إلى إعدادات المدفوعات العادية للعودة إلى المدفوعات العادية، عيّن للمتغير subscription سلسلة فارغة **stripe\_subscription = "**‌. في هذه الحالة، لن تؤثر المتغيرات interval و interval\_count على إنشاء الرابط.

### **إعدادات إلغاء الاشتراك** لإلغاء اشتراك في الآلة الحاسبة، استخدم **stripe\_remove\_subscription(stripe\_subscription\_id)** الطريقة، حيث إن **stripe\_subscription\_id** هو المعرّف الذي تم حفظه في معلومات الصفقة بعد الدفع. سيسمح لك ذلك بالإبقاء على اشتراكك المدفوع نشطًا حتى نهاية الفترة المدفوعة الحالية، ولكن لن تحدث رسوم إضافية، وسيتم إلغاء الاشتراك بعد تاريخ الانتهاء:

answer = stripe\_remove\_subscription('#{stripe\_subscription\_id}') stripe\_remove\_subscription - عند النجاح، ستتلقى استجابة تتضمن معلومات عن التاريخ الذي يظل الاشتراك الملغى صالحًا حتىه. في هذا المثال، سيتم وضع نتيجة تنفيذ الدالة في المتغير answer وسيكون من الممكن التحقق من نتيجة التنفيذ. ### التحقق من حالة الاشتراك **stripe\_check\_subscription(subscription\_id, customer\_id)**، حيث **stripe\_subscription\_id** - معرّف الاشتراك \ **stripe\_customer\_id** - معرّف العميل في Stripe (معامل اختياري)

## كيفية إنشاء قسيمة والحصول على معرّف الخصم للحصول على معرّف الخصم، أنشئ قسيمة في حسابك الشخصي في قسم ”coupons”. الرابط ”[coupons](https://dashboard.stripe.com/coupons)".

بعد النقر على زر “New”، تُفتح صفحة تحتاج فيها إلى تحديد: 1. الاسم — اسم الخصم؛ 2. ID — معرّف يتم إنشاؤه تلقائيًا. 3. النوع — نوع الخصم: نسبة مئوية أو مبلغ ثابت 4. المدة — مدة الخصم (لمرة واحدة أو متكرر، مثلًا للاشتراكات) ومعلمات أخرى.

ستظهر قسيمة الخصم في “Product catalog“ ضمن قسم “Coupons”، ويمكنك عرض معرّف الخصم بالانتقال إلى قائمة القسيمة:

انقر على القسيمة لنسخ معرّف القسيمة:

### كيفية إضافة خصم إلى الطلب 1. عند إنشاء رابط دفع (لكل من الاشتراكات والمدفوعات لمرة واحدة). في الآلة الحاسبة الخاصة بالكتلة، قبل تعريف **payment\_sum** المتغير، عيّن المتغير **coupon\_id** المتغير بإسناد معرّف الخصم من الحساب الشخصي في Stripe إليه.

2. للإضافة إلى اشتراك موجود باستخدام **stripe\_add\_subscription\_discount** . قم بتعيين شروط تشغيل الكتلة واستدعِ الدالة المحددة في الآلة الحاسبة، مع تمرير المعاملين stripe\_subscription\_id (معرّف الاشتراك) و coupon\_id (معرّف قسيمة الخصم) إليها. سيتم تطبيق الخصم على مدفوعات الاشتراك اللاحقة.

مثال على كود للنسخ

`stripe_subscription = 'اشتراك بريميوم'` \ `interval = 'month'` \ `payment_description = 'دفعة اختبارية في Stripe'` \ `currency = 'USD'` \ `coupon_id = 'معرّف قسيمتك'` \ `stripe_add_subscription_discount(stripe_subscription_id, coupon_id)` \ `stripe_tax_id = 'معرّف الضريبة'` \ `payment_sum = 90`

عند الإضافة بنجاح، تُرجع الدالة رسالة تشير إلى معرّف الاشتراك، والنوع، والمبلغ أو نسبة الخصم، وكذلك تاريخ انتهاء صلاحيته.

{% hint style="info" %} لمزيد من المعلومات حول إنشاء اشتراك، راجع قسم "كيفية إعداد المدفوعات المتكررة" الرابط "[كيفية إعداد المدفوعات المتكررة](#kak-nastroit-rekurrentnye-platezhi)" {% endhint %} ### كيفية حذف/تغيير خصم الاشتراك يمكن حذف الخصم المرفق بالاشتراك أو استبداله بخصم آخر. إذا كنت تريد إنهاء الخصم، فعيّن شرطًا لتشغيل الكتلة واستدعِ **stripe\_remove\_subscription\_discount** الدالة في الآلة الحاسبة، مع تمرير **stripe\_subscrition\_id** المعامل (معرّف الاشتراك) إليها.

عند إتمام العملية بنجاح، تُرجع الدالة رسالة تحتوي على معرّف الاشتراك وتاريخ إلغاء الخصم. يتم استبدال الخصم، وكذلك إضافة خصم جديد، باستخدام **stripe\_add\_subscription\_discount** الدالة. لا تنسَ تمرير **stripe\_subscription\_id** و **coupon\_id** المعلمات إليها.\ سيقوم الطلب الناجح بتحديث القسيمة المرفقة بالاشتراك وإرجاع رسالة بالمعلومات الحالية. {% hint style="info" %} يمكنك قراءة كيفية الحصول على معرّف الخصم في قسم "كيفية إنشاء قسيمة والحصول على معرّف الخصم". الرابط "[كيفية إنشاء قسيمة والحصول على معرّف الخصم](#kak-sozdat-kupon-i-poluchit-id-skidki)". {% endhint %} ## كيفية معالجة النتيجة بعد الدفع الناجح، سيتم إرسال callbacks إلى البوت لإعلامك بأن الدفع تم بنجاح. ترى هذه الـ callbacks في النظام كرسائل من المستخدم، ولكي لا يتمكن المستخدم من إرسالها، فهي تتكون من أول 20 حرفًا من المفتاح السري مع اللاحقة success، على سبيل المثال: **sk\_live\_d35gky6d8ers\_success**

هذه الردود غير مرئية للمستخدم، وتظهر للمشغّل فقط. يجب أن يكون نوع المقارنة "**مطابقة تامة"** كذلك، بعد نجاح الدفع، يتم تعيين المتغير **stripe\_payment\_completed** إلى **True.** على سبيل المثال، يمكنك معالجة الدفع الناجح داخل كتلة شرطية وعرض الرسالة المناسبة للمستخدم:

بعد إكمال الدفع، ستتم إضافة المتغير **stripe\_callback\_data** سيتم إضافة متغير إلى العميل يحتوي على بيانات استجابة نظام الدفع للمعاملة المكتملة. يمكنك استخراج البيانات المطلوبة من القاموس الناتج باستخدام **get** . {% hint style="warning" %} لإجراء دفعة متكررة، تحتاج إلى إعادة تعيين payment\_sum والرابط الذي تم إنشاؤه سابقًا، ثم إعادة إسناد المتغير payment\_sum للحصول على رابط جديد. يمكنك تحديد القيمة السابقة. {% endhint %} ## **كيفية اختبار المدفوعات** لاختبار التكامل، يمكنك استخدام المفتاح السري من بيئة الاختبار. للقيام بذلك، بدّل إلى وضع الاختبار في الحساب الشخصي لـ Stripe باستخدام المفتاح الموجود في القائمة اليمنى ![](https://lh5.googleusercontent.com/r-tuJboMES8alkTUpKwA4HKrmL_epNtSXdENrv12EyR9dGCtvRLBK6qw4UGcr59GA3unxc1cV1otCu80nqHEw9VhbEK05ovPQ1Ad8chBv50LAWPO16nEPC2hFhCAsCe3khtBJrob=s0) بعد ذلك، نفّذ الإعداد الموضح في بداية هذا الدليل. أدخل المفتاح السري الاختباري وأضف عنوان الـ webhook إلى بيئة الاختبار. رقم بطاقة الاختبار 4242 4242 4242 4242\ أي تاريخ في المستقبل\ CVC - أي ثلاثة أرقام إذا لم يعمل شيء ما، فقارن البيانات بالبيانات الموجودة على الموقع الرسمي. الرابط[ على الموقع الرسمي.](https://stripe.com/docs/testing#regulatory-cards) --- # 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/stripe.md?ask= ``` 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.