Bepaid (ru)

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

لتوصيل نظام الدفع bePaid ستحتاج إلى معرّف المتجر والمفتاح السري والمفتاح العام. بعد الحصول عليها، ننتقل إلى الإعدادات في MaviBot.

في MaviBot نفتح قسم "الاستحواذ"، ونختار bePaid. يجب إدخال البيانات المستلمة.

يرجى ملاحظة أن الحقل الأخير هو مفتاح تبديل لاستضافة API حسب بلد الاستخدام: بيلاروسيا أو روسيا.

كيفية إنشاء رابط للدفع

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

يكون الرابط بالشكل التالي: https://checkout.bepaid.by/widget/hpp.html?token=a05eabd3f9368725efbc175614c7d469da08f198cc51916b07fb75e53f9a3e1a

كذلك، قبل تعيين قيمة المتغير payment_sum، يمكن تعيين المتغيرات الاختيارية التالية لإعداد الدفع.

افتراضيًا يتم تعيين الروبل البيلاروسي، وإذا كانت هناك حاجة إلى عملة أخرى فيجب تعيين قيمة المتغير currency

معلمات الدالة	وصف المعلمة	إضافيًا
currency	عملة الدفع بصيغة ISO-4217 تنسيق	على سبيل المثال USD
language	لغة صفحة الدفع القيمة الافتراضية - en.	القيم المسموح بها: en - الإنجليزية es - الإسبانية tr - التركية de - الألمانية it - الإيطالية ru - الروسية zh - الصينية fr - الفرنسية da - الدنماركية sv - السويدية no - النرويجية fi - الفنلندية pl - البولندية ja - اليابانية uk - الأوكرانية be - البيلاروسية ka - الجورجية ro - الرومانية
payment_description	وصف الدفع
link_expired	مدة صلاحية رابط الدفع، بصيغة يوم.شهر.سنة (على سبيل المثال 25.06.2025). افتراضيًا يجب أن يتم الدفع خلال 24 ساعة	يمكن أيضًا في الحقل "تعيين المتغيرات عند الانتقال" تحديد: link_expired = current_date + 2 (سيكون الرابط صالحًا لمدة يومين حتى 00:00) link_expired كما يمكن أيضًا تحديد تاريخ مع وقت دقيق، مع ترك مسافة، بصيغة يوم.شهر.سنة ساعة:دقيقة (على سبيل المثال: 25.06.2025 12:23). افتراضيًا يجب أن يتم الدفع خلال 24 ساعة يمكن أيضًا استخدام المتغيرات القياسية، على سبيل المثال لنعيّن مدة صلاحية الرابط 30 دقيقة: time = current_time + 30 link_expired = "#{current_date} #{time}"
russian_host	مؤشر تسجيل المتجر على المضيف الروسي لـ bePaid. حدّد هذه المعلمة بالقيمة 1 إذا كان متجرك مسجلًا على موقع bepaid.tech	إذا كان من الضروري التبديل إلى المضيف البيلاروسي، فحدّد المعلمة بالقيمة ''
test_payments	هذا المتغير مطلوب للمدفوعات الاختبارية، وإذا كنت تحتاج إلى دفعة اختبارية فأضفه بأي قيمة.
bepaid_attempts	يشير إلى عدد محاولات إتمام الدفع، ويتم منح محاولة واحدة افتراضيًا.
сustomer_data	مصفوفة تحتوي على first_name و last_name و email الخاصة بالدافع. هذه البيانات ضرورية لإرسال الإيصال إلى بريد الدافع الإلكتروني، وهي متاحة للتحرير في صفحة الدفع.	يجب تمرير المعلمة على شكل قائمة بصيغة json، تتكون من أزواج مفتاح-قيمة على سبيل المثال: customer_data = ‘{“first_name”: “Vladimir”, “last_name”: “Popov”, “email”: “[email protected]” }’
bepaid_contract (شرطيًا إلزامي)	غرض الدفع عبر الرمز المميز.	القيم المتوقعة: “recurring” (للمدفوعات المنتظمة ذات الدورية المحددة) أو “card_on_file” (للمدفوعات غير المنتظمة، مثل الدفع اللاحق مقابل خدمة مقدمة)

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

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

لإجراء دفعة اختبارية، قبل تحديد المتغير payment_sum، يجب تعيين المتغير test_payments بأي قيمة.

لا تنسَ إزالته عند تشغيل البوت في الوضع الفعلي!

بطاقات للاختبارات:

4200000000000000 ناجح

4005550000000019 فاشل

إذا كان هناك شيء لا يعمل، فقارن البيانات بالبيانات الموجودة على الموقع الرسمي: https://docs.bepaid.by/ru/test-integration#test-card-number

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

لننشئ رابط دفع بقيمة 100 روبل بيلاروسي (العملة الافتراضية)

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

بعد ذلك، في المكان المطلوب نعرض المتغير bepaid_pay_url، الذي يحتوي على الرابط

إدارة الاشتراكات

يوفر تكامل نظام الدفع إمكانية إنشاء اشتراكات لعملائك.

قبل البدء في استخدام وظائف MaviBot، أنشئ خطة اشتراك في الحساب الشخصي لـ bePaid.

إذا لم تظهر قائمتا “الخطط” و“الاشتراكات” في الحساب الشخصي، فتواصل مع مديرك.

إنشاء اشتراك والحصول على رابط الدفع

استخدم الوظيفة get_bepaid_subscription_url، مع تمرير المعلمة plan_id إليها، حيث

plan_id	هو معرّف الخطة في نظام bePaid.

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

أرسل الرابط إلى العميل وانتظر اكتمال الدفع.

عند نجاح الدفع، سيتم تفعيل الاشتراك، وستُضاف إلى الصفقة المتغيرات bepaid_subscription_id و bepaid_subscription_status، كما سيصل إلى البوت رد نداء (انظر القسم “كيفية معالجة النتيجة”).

الحصول على معلومات الاشتراك

للحصول على بيانات اشتراك العميل الحالي، استدعِ الوظيفة get_bepaid_subscription_info، مع تمرير المعلمة subscription_id إليها (يمكن أخذ القيمة من المتغير bepaid_subscription_id).

إلغاء الاشتراك

لإلغاء الاشتراك، استخدم الوظيفة cancel_bepaid_subscription.

تقبل هذه الوظيفة معلمة واحدة فقط هي subscription_id (يمكن أخذ القيمة من المتغير bepaid_subscription_id).

عند الإلغاء الناجح، سيأخذ المتغير bepaid_subscription_status القيمة “canceled”، كما سيصل إلى البوت رد نداء (انظر القسم “كيفية معالجة النتيجة”).

حالات الاشتراكات

trial	اشتراك تجريبي نشط أو ملغى.
active	اشتراك نشط تم فيه السداد في الموعد المحدد.
failed	اشتراك فاشل. لم يتمكن bePaid من إجراء الدفعة التالية.
error	حدث خطأ عند محاولة bePaid إجراء الدفع.
canceled	تم إلغاء الاشتراك ولم يعد ساريًا.

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

يمكنك أيضًا تنظيم نظام اشتراكات دون إنشاء خطة في الحساب الشخصي لـ bePaid.

ولهذا ستحتاج إلى رمز بطاقة العميل.

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

قبل تعيين قيمة payment_sum، عيّن المتغير bepaid_contract، وحدد فيه غرض المدفوعات المستقبلية عبر الرمز: “recurring” للمدفوعات المنتظمة ذات الدورية المحددة أو “card_on_file” للمدفوعات غير المنتظمة (على سبيل المثال، الدفع اللاحق مقابل خدمة مقدمة).

الخيار “card_on_file” غير مدعوم من جميع جهات الاستحواذ. إذا كنت ترغب في استخدامه، فتواصل مع مدير الحساب الخاص بك.

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

بعد ذلك قم بإعداد القمع وحدد التاريخ أو الشرط للخصم التلقائي واستدعِ وظيفة الآلة الحاسبة make_bepaid_token_payment، مع تمرير المعلمات المطلوبة إليها.

ترتيب المعلمات:

amount -> currency -> description -> contract

وصف المعلمات:

amount (إلزامي)	مبلغ الدفع، والقيمة المتوقعة عدد صحيح أو عشري، على سبيل المثال 100 أو 100.5؛
currency (إلزامي)	عملة الدفع بصيغة ISO-4217 بصيغة، على سبيل المثال “USD”
description (إلزامي)	وصف سبب الخصم، على سبيل المثال، “دفع اشتراك أسبوعي للمشاركة في نادي الهوايات”;
contract (إلزامي)	غرض الدفع عبر الرمز. القيم المتوقعة: “recurring” أو “card_on_file”.

يجب أن تتطابق قيمة contract بالضرورة مع القيمة المحددة عند إنشاء رابط الدفعة التأسيسية!

إذا تم الدفع بنجاح، فستُرجع الوظيفة الرسالة “خصم ناجح عبر رمز bePaid“، وستتلقى رد نداء عن الدفع الناجح، وسيأخذ متغير الصفقة bepaid_token_payment_completed القيمة “True”.

إذا لم ينجح الدفع، فستُرجع الوظيفة رسالة تشير إلى سبب فشل الدفع، وسيصل إلى البوت رد نداء مع اللاحقة “_fail”، وسيأخذ متغير الصفقة bepaid_token_payment_completed القيمة “False”.

قد يطلب البنك من العميل إكمال الدفع. في هذه الحالة، ستُرجع الوظيفة رابطًا مع طلب اجتياز مصادقة 3-D Secure.

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

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

في النظام، يبدو رد النداء كرسالة من المستخدم، إلا أن المستخدم نفسه لا يراها.

للمدفوعات

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

رقم_المفتاح_success - عند نجاح الدفع؛

رقم_المفتاح_fail - عند فشل الدفع؛

يمكن أيضًا تتبع حالة آخر دفعة من خلال المتغيرين bepaid_payment_completed (للمدفوعات بمشاركة العميل) و bepaid_token_payment_completed (للمدفوعات غير المقبولة مسبقًا عبر رمز البطاقة)

للاشتراكات

بعد التفعيل الناجح للاشتراك عند الدفعة الأولى أو المتكررة، ستصل إلى البوت رسالة رقم_المفتاح_success.

إذا تم إلغاء الاشتراك، فستتلقى رقم_المفتاح_canceled.

في حالة فشل الدفع الخاص بالاشتراك، ستصلك رسالة رقم_المفتاح_fail.