Bepaid

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

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

للحصول على معرّف المتجر, المفتاح السري، و المفتاح العام، يرجى الاتصال بـ baPaid الدعم الفني للمساعدة.

في MaviBot، افتح قسم "نظام الدفع" وانتقل إلى bePaid. ثم أدخل بيانات الاعتماد التي تلقيتها.

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

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

لإنشاء رابط دفع، تحتاج إلى تعيين قيمة للمتغير payment_sum (على سبيل المثال: 150 أو 100.55 — استخدم نقطة كفاصل عشري).

بمجرد تعيين payment_sum المتغير، سيظهر المتغير 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	انتهاء صلاحية رابط الدفع عيّن تاريخ الانتهاء بالتنسيق dd.mm.yyyy (على سبيل المثال: 25.06.2025). افتراضيًا، يجب إكمال الدفع خلال 24 ساعة.	يمكنك أيضًا استخدام الحقل "تعيين المتغيرات عند إعادة التوجيه" لتعيين: link_expired = current_date + 2 — سيكون الرابط صالحًا لمدة يومين حتى 00:00. يمكنك أيضًا تحديد تاريخ ووقت انتهاء دقيق بالتنسيق dd.mm.yyyy hh:mm (على سبيل المثال: 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	مصفوفة تحتوي على الاسم الأول, اسم العائلة، و البريد الإلكترونيللدافع. هذه البيانات مطلوبة لإرسال الإيصال إلى بريد الدافع الإلكتروني ويمكن تعديلها في صفحة الدفع.	يجب تمرير المعلمة كـ قائمة أزواج مفتاح-قيمة بتنسيق JSON. على سبيل المثال: customer_data = ‘{“first_name”: “Sam”, “last_name”: “Smith”, “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 في الموقع المطلوب؛ فهو يحتوي على رابط الدفع المُنشأ.

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

يسمح لك تكامل نظام الدفع بإنشاء اشتراكات لعملائك.

قبل استخدام هذه الوظيفة في Salebot، أنشئ خطة اشتراك في bePaid حسابك.

إذا كان "الخطط" و "الاشتراكات" إذا لم تظهر القوائم في حسابك، فيرجى الاتصال بمديرك.

إنشاء اشتراك وإنشاء رابط دفع

استخدم الدالة get_bepaid_subscription_url مع تمرير المعلمة plan_id ، حيث…

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	تم 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 (مطلوب)	وصف الخصم، على سبيل المثال: “Weekly subscription payment for participation in the hobby club”.
contract (مطلوب)	غرض الدفع بواسطة الرمز. القيم المتوقعة: “recurring” أو “card_on_file”.

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

إذا كان الدفع ناجحًا، ستعيد الدالة الرسالة “Successful charge via bePaid token”، وستتلقى استدعاءً للدفع الناجح، وسيتم تعيين متغير الصفقة bepaid_token_payment_completed إلى “True”.

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

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

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

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

في النظام، يظهر الاستدعاء كرسالة من المستخدم، لكن المستخدم لا يراه.

للدفعات

بالنسبة للمدفوعات غير المرتبطة بالاشتراكات، ستتلقى إحدى الرسائل التالية:

• keyNumber_success – للدفع الناجح

• keyNumber_fail – للدفع الفاشل

يمكنك أيضًا تتبع حالة آخر دفعة باستخدام المتغيرات:

• bepaid_payment_completed – للمدفوعات التي تتضمن العميل

• bepaid_token_payment_completed – لـ المدفوعات التلقائية المعتمدة على رمز البطاقة

للاشتراكات

بعد تفعيل الاشتراك بنجاح، سواء في الدفعة الأولى أو الدفعة المتكررة، سيتلقى البوت الرسالة keyNumber_success.

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

في حالة فشل دفع الاشتراك، سيتم إرسال الرسالة keyNumber_fail .