Stripe

كيفية الاتصال

لاتصال بنظام الدفع Stripe، ستحتاج إلى مفتاح API سري ومفتاح webhook.

يمكن نسخ مفتاح API السري بالذهاب إلى Developers → API keys ونسخ المفتاح السري.

الخطوة 1. اذهب إلى Developers → API keys:

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

بعد ذلك، تحتاج إلى تعيين عنوان URL للرد. هذا يسمح للبوت باستلام إشعارات الدفع.

اذهب إلى قسم Webhooks وأضف عنوان URL للwebhook.

سيظهر نموذج.

الخطوة 3. انقر على "+add destination".

الخطوة 4. حدد الأحداث.

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

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

الخطوة 5. أدخل اسمًا وحدد عنوان URL للنقطة النهائية.

اضبط عنوان URL على: https://chatter.mavibot.ai/stripe_callback/result

الخطوة 6. سيتم إنشاء نقطتين نهائيتين — يمكنك مراجعة الإعدادات قبل إضافتهما.

الخطوة 7. انقر على زر "Add destinations". سيتم حفظ الwebhooks.

الخطوة 8. انقر على "Done".

احفظ وستنتقل إلى الصفحة التي تحتوي على الwebhook الذي تم تكوينه.

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

الخطوة 10. ابحث عن مفتاح التوقيع واحفظه (ستحتاجه لاحقًا للاتصال بـ MaviBot).

بمجرد حصولك على المفاتيح، تابع الاتصال في Mavibot.

في Mavibot، افتح قسم "Acquiring" واختر Stripe.

في صفحة الاتصال، أدخل المفاتيح التي حصلت عليها.

انقر على "Save settings".

تم! لقد قمت بتوصيل Stripe.

كيفية توصيل رد حالة المعاملة

لاستقبال رد إضافي، تحتاج إلى إضافة webhook ثانٍ بجانب الموجود.

اضبط عنوان URL على: https://chatter.mavibot.ai/stripe_callback/<api_key>/charge_status

وحدد الأحداث التالية:

• charge.failed
• charge.pending
• charge.succeeded

مزيد من التفاصيل حول كل نوع 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

أضف مفتاح webhook الذي تم الحصول عليه بعد الحفظ إلى حقل Mavibot — Webhook key2.

stripe_invoice_id — معرف المعاملة التي لم يتم استلام رد الدفع الناجح لها مباشرة بعد الدفع.

كيفية إعداد الضرائب

لاستخدام الضرائب في المدفوعات، تحتاج أولاً إلى إنشائها في لوحة تحكم Stripe الخاصة بك. للقيام بذلك، اكتب "tax rates" في شريط البحث:

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

ثم أدخل معدل الضريبة المطبق.

في القائمة التي تفتح، حدد نوع الضريبة، والمنطقة التي تنطبق عليها، والنسبة المئوية، وما إذا كانت الضريبة ستُضمن في مبلغ الدفع (Inclusive) أو ستُضاف إليه (Exclusive).

بعد إنشاء معدل الضريبة، انسخ معرفه إلى متغير stripe_tax_id قبل الإعلان عن مبلغ الدفع.

لتجنب الأخطاء، يُوصى بتعيين متغير stripe_tax_id إلى سلسلة فارغة ("") بعد استلام الرابط — بهذه الطريقة يمكنك تطبيق الضريبة فقط عند الحاجة.

إذا تم ذلك بشكل صحيح، في حالة معدل ضريبة مع المعامل الحصري، سترى ما يلي:

كيفية الحصول على رابط الدفع

لإنشاء رابط دفع، قم بتعيين قيمة متغير payment_sum (على سبيل المثال 150 أو 100.55 — استخدم نقطة، وليس فاصلة!). بعد ذلك، سيظهر متغير stripe_pay_url. يمكنك عرض هذا المتغير كرابط أو وضعه على زر مع نص "Pay".

يبدو الرابط هكذا:

https://checkout.stripe.com/pay/cs_test_a17mskKFFRwEuo3WgBSAUjfk7xaZZIrct9B3Ds2AdODVq1I8aRiqYEBdrU#fidkdWxOYHwnPyd1blpxYHZxWjA0TGFsVzFPVmpmMzJAbVYzUkp1Y0lLYDVgfzR2Q0NxcWZBNUNnTnRSVVRJSGFobEB1UExSczRMMTc8PWRLMGBddl8xalxyPDRoUGhnZm9xXXZANDZyaF0wNTVBVExsPHZyfycpJ2N3amhWYHdzYHcnP3F3cGApJ2lkfGpwcVF8dWAnPyd2bGtiaWBabHFgaCcpJ2BrZGdpYFVpZGZgbWppYWB3dic%2FcXdwYHgl

افتراضيًا، العملة مضبوطة على USD. لاستخدام عملة مختلفة، قم بتعيين قيمة متغير currency.

يمكنك أيضًا تعيين المتغيرات الاختيارية التالية قبل تعيين قيمة payment_sum لتكوين الدفع.

معلمات الوظيفة	وصف المعلمة
currency	عملة الطلب. القيم المسموح بها هنا —https://stripe.com/docs/currencies
payment_description	وصف الدفع
stripe_tax_id	معرف معدل الضريبة الذي تم تكوينه في لوحة تحكم Stripe الخاصة بك. تعليمات الإعداد موجودة في قسم "كيفية إعداد الضرائب".
stripe_invoice_enable	علامة لتمكين حفظ الفواتير (الإيصالات). قم بتعيين أي قيمة لتمكين ذلك — ستكون جميع المستندات ذات الصلة متاحة في لوحة تحكم Stripe الخاصة بك.
stripe_locale	تعيين لغة صفحة الدفع: en، de، إلخ. جميع الخيارات المتاحة: https://stripe.com/docs/api/checkout/sessions/create#create_checkout_session-locale إذا لم يتم تعيين stripe_locale، فسيتم استخدام لغة متصفح العميل.
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_payment_method_type و stripe_additional_payment_method_type، فيجب أن تكون القيم فيهما مختلفة!

قائمة القيم لـ 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

مثال على إنشاء رابط الدفع

لنقم بإنشاء رابط دفع بقيمة 1000 AED (العملة الافتراضية هي USD).

ملاحظة:

— أولاً، حدد المعلمات الاختيارية مثل first_name، payment_description، إلخ.

— ثم، قم بتعيين القيمة لمتغير payment_sum أخيرًا.

يمكن أيضًا تعيين المتغيرات في وقت سابق في السلسلة، وليس بالضرورة في نفس الكتلة — هذا مجرد مثال.

ثم اعرض متغير stripe_pay_url، الذي يحتوي على الرابط، في النقطة المطلوبة — إما في كتلة رسالة أو على زر:

مثال 1. عرض رابط الدفع مباشرة في رسالة:

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

عند النقر على الزر أو اتباع الرابط، سيتم إعادة توجيه الدافع إلى صفحة الدفع.

يوضح المثال أن المعلمات التي حددناها في الآلة الحاسبة في إعدادات الكتلة قد تم تطبيقها: وصف الطلب، العملة، والمبلغ.

إذا قمت بتمرير معلمة معدل الضريبة (stripe_tax_id) في الكتلة.

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

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

payment_description = "test payment"

currency = 'AED'

stripe_tax_id = 'enter_your_stripe_id_tax'

payment_sum = 1000

أين تجد معرف الضريبة.

كيفية إعداد المدفوعات المتكررة

للمدفوعات المتكررة (الاشتراكات)، قم بتعريف متغير stripe_subscription قبل متغير payment_sum وقم بتعيينه اسم الاشتراك.

يمكنك أيضًا إضافة المتغيرات التالية: interval — مدة الفاصل الزمني للاشتراك. مرر 'day' للأيام، 'week' للأسابيع، 'month' للأشهر، أو 'year' للسنوات. إذا لم يتم تعيين المتغير، فسيتم استخدام 'month' افتراضيًا.

مهم!

لا يمكن أن تتجاوز مدة دورة اشتراك واحدة سنة واحدة (للمعامل 'year')، أو 12 شهرًا (للمعامل 'month')، أو 52 أسبوعًا (للمعامل 'week').

interval_count — عدد الفواصل الزمنية المحددة: كم يومًا أو أسبوعًا أو شهرًا مضمنة في الاشتراك للمبلغ المحدد. الافتراضي هو 1.

stripe_payment_method_type — طريقة الدفع؛ الافتراضي هو الدفع بالبطاقة. يمكن استبداله بطرق دفع أخرى متاحة في Stripe. الطرق المتاحة مذكورة أدناه.

على سبيل المثال، stripe_payment_method_type = 'customer_balance'

stripe_additional_payment_method_type — إضافة وسيلة دفع إضافية. الطرق المتاحة مذكورة أدناه.

على سبيل المثال، stripe_additional_payment_method_type = 'sepa_debit'

مهم! إذا كنت تستخدم كلاً من المتغيرين stripe_payment_method_type و stripe_additional_payment_method_type، فيجب أن تكون القيم فيهما مختلفة!

قائمة القيم لـ 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.

مهم!

لا يمكن أن تتجاوز مدة دورة الاشتراك الواحدة سنة واحدة (للمعامل 'year')، أو 12 شهرًا (للمعامل 'month')، أو 52 أسبوعًا (للمعامل 'week').

في هذا المثال، سيتم إنشاء اشتراك باسم 'My_subscription' بسعر 1000 درهم إماراتي شهريًا، وسيتم خصم دفعة متكررة بنفس المبلغ بعد شهر واحد.

مثال للنسخ:

stripe_subscription = 'My_subscription' interval = 'month' payment_sum = 90

لخصم دفعة الاشتراك مرة كل شهرين أو ثلاثة أو أربعة أشهر، قم بتمرير المعامل interval_count:

stripe_subscription = 'My_subscription'

interval = 'month'

interval_count = 3

payment_sum = 90

لتغيير فترة دفع الاشتراك من شهرية إلى أسبوعية، قم بتمرير الكلمة week في المعامل interval:

stripe_subscription = 'My_subscription'

interval = 'week'

interval_count = 3

payment_sum = 90

بعد الدفع، ستتضمن متغيرات معاملة العميل stripe_subscription_id، وهو ضروري لتكوين إلغاء الاشتراك، و stripe_customer_id، والذي يمكن استخدامه لاحقًا للتحقق من حالة الاشتراك.

يتم إرسال الإشعار (الاستدعاء) فقط لأول دفعة متكررة!

لن يكون هناك استدعاء للدفعات اللاحقة. يتم التتبع عبر الوظيفة و stripe_customer_id.

إعدادات العودة إلى الدفعات العادية

للعودة إلى الدفعات العادية، قم بتعيين قيمة سلسلة فارغة لمتغير الاشتراك: 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 (معامل اختياري)

كيفية إنشاء قسيمة والحصول على معرف الخصم

للحصول على معرف الخصم، قم بإنشاء قسيمة في لوحة التحكم الخاصة بك ضمن قسم "القسائم". "القسائم".

سيؤدي النقر على زر "جديد" إلى فتح صفحة حيث تحتاج إلى تحديد:

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

ستظهر قسيمة الخصم في "كتالوج المنتجات" ضمن قسم "القسائم"، ويمكنك عرض معرف الخصم بفتح قائمة القسيمة.

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

كيفية تطبيق خصم على طلب

1. عند إنشاء رابط الدفع (يعمل لكل من الاشتراكات والدفعات لمرة واحدة).

في حاسبة الكتلة، قبل تعريف متغير payment_sum، قم بتعيين متغير coupon_id وتمرير معرف الخصم من لوحة تحكم Stripe الخاصة بك.

2. على اشتراك موجود باستخدام الوظيفة stripe_add_subscription_discount.

قم بتعيين شروط تشغيل الكتلة واستدعاء الوظيفة المحددة في الحاسبة، مع تمرير المعاملات stripe_subscription_id (معرف الاشتراك) و coupon_id (معرف خصم القسيمة). سيتم تطبيق الخصم على دفعات الاشتراك اللاحقة.

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

stripe_subscription = 'test subscription'

interval = 'month'

payment_description = 'test payment'

currency = 'AED'

coupon_id = 'BD8VIwi8' stripe_add_subscription_discount(stripe_subscription_id, coupon_id)

stripe_tax_id = 'Qfkiwiki29jcs'

payment_sum = 90

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

كيفية إزالة أو تغيير خصم لاشتراك

يمكن إزالة الخصم المرتبط باشتراك أو استبداله بخصم آخر.

لإيقاف الخصم، قم بتعيين شروط تشغيل الكتلة واستدعاء الوظيفة stripe_remove_subscription_discount في الحاسبة، مع تمرير المعامل stripe_subscription_id (معرف الاشتراك).

إذا كانت العملية ناجحة، فستُرجع الوظيفة رسالة تحتوي على معرف الاشتراك وتاريخ إلغاء الخصم.

استبدال الخصم، مثل إضافة خصم جديد، يتم باستخدام الوظيفة stripe_add_subscription_discount. تأكد من تمرير المعاملات stripe_subscription_id و coupon_id. سيؤدي الطلب الناجح إلى تحديث القسيمة المرتبطة بالاشتراك وإرجاع رسالة بالتفاصيل المحدثة.

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

بعد الدفع الناجح، سيتلقى الروبوت استدعاءات تشير إلى معاملة ناجحة. في النظام، تظهر هذه الاستدعاءات كرسائل من المستخدم. لمنع المستخدمين من إرسالها يدويًا، تتكون من أول 20 حرفًا من المفتاح السري متبوعًا بـ _success، على سبيل المثال: sk_live_d35gky6d8ers_success

هذه الاستدعاءات غير مرئية للمستخدم — فهي مرئية فقط للمشغل.

يجب تعيين نوع المقارنة على "مطابقة تامة".

بعد الدفع الناجح، يتم أيضًا تعيين المتغير stripe_payment_completed إلى True.

على سبيل المثال، يمكنك التعامل مع الدفع الناجح باستخدام كتلة شرطية وعرض الرسالة المناسبة للمستخدم.

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

لمعالجة دفعة متكررة، يجب عليك أولاً إعادة تعيين payment_sum والرابط الذي تم إنشاؤه مسبقًا، وبعد ذلك فقط إعادة تعيين متغير payment_sum للحصول على رابط جديد. يمكنك استخدام القيمة السابقة.

كيفية اختبار الدفعات

لاختبار التكامل، يمكنك استخدام المفتاح السري من بيئة الاختبار. للقيام بذلك، قم بالتبديل إلى بيئة الاختبار في لوحة تحكم Stripe باستخدام القائمة على اليمين.

ثم اتبع خطوات الإعداد الموضحة في بداية هذا الدليل. أدخل المفتاح السري للاختبار وأضف عنوان URL للويب هوك في بيئة الاختبار.

للاختبار، استخدم رقم بطاقة دفع اختبارية (يمكنك العثور على رقم البطاقة لبلدك على موقع Stripe الرسمي).