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

للاتصال بنظام الدفع 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".

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

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

بعد إنشاء معدل الضريبة، انسخ معرفه إلى المتغير 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 لتكوين الدفع.

مهم! إذا كنت تستخدم كلاً من المتغيرين 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، فيجب أن تكون القيم فيهما مختلفة!

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 AED شهريًا، وسيتم خصم دفعة متكررة بنفس المبلغ بعد شهر واحد.

مثال للنسخ:

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 (معلمة اختيارية)

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

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

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

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

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

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

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

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

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

  1. على اشتراك موجود باستخدام الوظيفة 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

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

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

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

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

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

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

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

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

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

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