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 - https://chatter.salebot.pro/stripe_callback/result

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

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

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

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

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

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

بعد استلام المفاتيح، ننتقل إلى الاتصال بـ Mavibot.

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

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

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

تم!

بهذا يكتمل توصيل نظام الدفع!

كيفية توصيل رد نداء بشأن حالة المعاملة

للحصول على رد نداء إضافي، سنحتاج إلى توصيل webhook في إضافةً إلى الموجود بالفعل.

حدد عنوان URL - https://chatter.salebot.pro/stripe_callback/<api_key>/charge_status

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

charge.failed
charge.pending
charge.succeeded

تعرّف أكثر على كل نوع من أنواع webhook:

charge.succeeded - يحتوي على معلومات حول إتمام المعاملة بنجاح (مشابه لرد نداء حول الدفع الناجح)
charge.pending - "المعاملة قيد التنفيذ"، وقد يستغرق إكمالها حتى 7 أيام. سيبدو الـ webhook بالشكل {أول 10 أحرف }{نوع الـ webhook} على سبيل المثال: sk_test_45LDPJLKT95d_charge.pending
charge.failed - "فشلت المعاملة." سيبدو الـ webhook بالشكل {أول 10 أحرف }{نوع الـ webhook} على سبيل المثال: sk_test_45LDPJLKT95d_charge.failed

نضيف الـ 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

افتراضيًا، يتم تعيين USD (الدولار)، وإذا كنت بحاجة إلى عملة أخرى، فيجب تعيين قيمة currency .

كذلك، قبل تعيين قيمة 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

انتباه! إذا كنت تستخدم كِلا 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 روبل (الافتراضي هو الدولار)

انتبه: - أولاً تحدد المعلمات الاختيارية first_name, payment_description وهكذا. - وأخيرًا نُسند قيمة إلى المتغير payment_sum

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

بعد ذلك، في المكان المطلوب نعرض المتغير stripe_pay_url، والذي يحتوي على الرابط داخل الكتلة أو في الزر:

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

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

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

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

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

جميع الخيارات الثلاثة مقبولة لإرسال رابط الدفع في البوت.

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

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

إذا قمت بتمرير معلمة معدل الضريبة (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’.

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

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'

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

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

لمزيد من المعلومات حول كل طريقة والبلدان التي تتوفر فيها، راجع وثائق Stripe: انظر الموقع الرابط عرض على الموقع

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

في هذا المثال، سيتم إنشاء اشتراك باسم 'My_subscription' بسعر 90 دولارًا أمريكيًا لمدة 3 أشهر، وسيتم إجراء دفعة متكررة بنفس المبلغ بعد هذا الشهر الواحد:

مثال للنسخ:

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

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

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

لن يكون هناك callback للمدفوعات المتكررة اللاحقة. يتم التحكم عبر الدالة و stripe_customer_id. عبر الدالة رابط

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

للعودة إلى المدفوعات العادية، عيّن للمتغير 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".

بعد النقر على زر “New”، تُفتح صفحة تحتاج فيها إلى تحديد:

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

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

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

كيفية إضافة خصم إلى الطلب

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

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

للإضافة إلى اشتراك موجود باستخدام 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

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

لمزيد من المعلومات حول إنشاء اشتراك، راجع قسم "كيفية إعداد المدفوعات المتكررة" الرابط "كيفية إعداد المدفوعات المتكررة"

كيفية حذف/تغيير خصم الاشتراك

يمكن حذف الخصم المرفق بالاشتراك أو استبداله بخصم آخر.

إذا كنت تريد إنهاء الخصم، فعيّن شرطًا لتشغيل الكتلة واستدعِ stripe_remove_subscription_discount الدالة في الآلة الحاسبة، مع تمرير stripe_subscrition_id المعامل (معرّف الاشتراك) إليها.

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

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

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

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

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

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

يجب أن يكون نوع المقارنة "مطابقة تامة"

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

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

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

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

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

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

بعد ذلك، نفّذ الإعداد الموضح في بداية هذا الدليل. أدخل المفتاح السري الاختباري وأضف عنوان الـ webhook إلى بيئة الاختبار.

رقم بطاقة الاختبار

4242 4242 4242 4242 أي تاريخ في المستقبل CVC - أي ثلاثة أرقام

إذا لم يعمل شيء ما، فقارن البيانات بالبيانات الموجودة على الموقع الرسمي. الرابط على الموقع الرسمي.

آخر تحديث قبل 4 أشهر