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

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

للحصول على معرف المتجر والمفتاح السري والمفتاح العام، اتصل بدعم bePaid الفني.

في MaviBot، افتح قسم الاستحواذ، واختر bePaid، وأدخل البيانات التي تلقيتها.

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

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

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

بمجرد تعيين متغير payment_sum، يتم إنشاء المتغير bepaid_pay_url تلقائيًا. يمكنك عرض هذا المتغير كرابط في رسالة أو استخدامه في زر مع النص "دفع".

معامل الوظيفة الوصف مزيد من المعلومات
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).

يمكن أيضًا استخدام المتغيرات القياسية. مثال لرابط صالح لمدة 30 دقيقة:

python\ntime = current_time + 30\nlink_expired = "#{current_date} #{time}"\n
russian_host مؤشر لمتجر مسجل على مضيف bePaid الروسي. قم بتعيين هذه المعلمة إلى 1 إذا كان متجرك مسجلاً على bepaid.tech. للتبديل إلى المضيف البيلاروسي، قم بتعيين هذه المعلمة إلى "" (قيمة فارغة).
test_payments يتيح الدفعات الاختبارية. قم بتعيين أي قيمة لهذا المتغير قبل إنشاء رابط الدفع. —
bepaid_attempts يحدد عدد محاولات الدفع. افتراضيًا، يُسمح بـ محاولة واحدة. —
customer_data كائن JSON يحتوي على الاسم الأول واسم العائلة والبريد الإلكتروني للدافع. هذه المعلومات مطلوبة لإرسال إيصال الدفع ويمكن تحريرها في صفحة الدفع. يجب تمرير المعامل كـ كائن بتنسيق JSON.

مثال:

python\ncustomer_data = {\n \"first_name\": \"Sam\",\n \"last_name\": \"Smith\",\n \"email\": \"[email protected]\"\n}\n
bepaid_contract (مطلوب بشروط) الغرض من الدفع للمدفوعات القائمة على الرمز المميز. القيم المسموح بها:

• recurring — للمدفوعات المتكررة بجدول زمني ثابت.
• card_on_file — للمدفوعات لمرة واحدة أو غير المنتظمة، على سبيل المثال، تحصيل رسوم من العميل بعد تقديم الخدمة.

مثال لرابط الدفع:

https://checkout.bepaid.by/widget/hpp.html?token=a05eabd3f9368725efbc175614c7d469da08f198cc51916b07fb75e53f9a3e1a

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

افتراضيًا، عملة الدفع هي الروبل البيلاروسي (BYN). إذا كنت ترغب في استخدام عملة أخرى، قم بتعيين قيمة للمتغير currency.

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

يمكنك استرداد القيم المطلوبة من هذا القاموس باستخدام الدالة get().

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

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

هام: قم بإزالة المتغير test_payments قبل تحويل البوت الخاص بك إلى الوضع المباشر.

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

رقم البطاقة النتيجة
4200000000000000 دفعة ناجحة
4005550000000019 دفعة فاشلة

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

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

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

أخيرًا، اعرض المتغير bepaid_pay_url حيثما كان ذلك مطلوبًا. يحتوي على رابط الدفع الذي تم إنشاؤه.

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

يتيح تكامل bePaid لك إنشاء اشتراكات لعملائك.

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

إذا كانت أقسام الخطط والاشتراكات غير متوفرة في حسابك، فاتصل بمدير حسابك.

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

استخدم الدالة get_bepaid_subscription_url ومرر المعامل plan_id.

تقوم الدالة بإنشاء اشتراك وإرجاع رابط دفع.

أرسل الرابط الذي تم إنشاؤه إلى العميل وانتظر حتى يتم إتمام الدفع.

بعد الدفع الناجح:

  • يتم تنشيط الاشتراك؛
  • تتلقى الصفقة المتغيرات:
    • 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

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

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

المعامل الوصف
amount (مطلوب) مبلغ الدفع. يجب أن تكون القيمة عددًا صحيحًا أو عشريًا، على سبيل المثال: 100 أو 100.5.
currency (مطلوب) عملة الدفع بتنسيق ISO 4217، على سبيل المثال: USD.
description (مطلوب) وصف الدفع، على سبيل المثال: "دفعة الاشتراك الأسبوعية للمشاركة في نادي الهوايات".
contract (مطلوب) الغرض من الدفع بالرمز المميز. القيم المسموح بها: recurring أو card_on_file.

إذا كان الدفع ناجحًا:

  • تقوم الدالة بإرجاع الرسالة "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