Paypal
كيف تُعدّ Paypal رابط How to set up Paypal
كيف تنشئ رابطًا للدفع رابط How to create a payment link
كيف تنشئ دفعة متكررة رابط How to create a recurring payment
كيفية معالجة النتيجة رابط How to process the result
How to set up Paypal
للعمل مع Paypal، تحتاج إلى الحصول على مفتاحين: client_id و secret
اذهب إلى الصفحة https://developer.paypal.com/developer/applications/
واختر من القائمة أو أنشئ تطبيقًا جديدًا:
في الأعلى، بدّل إلى وضع Live وحدد التطبيق المطلوب. ستفتح صفحة الإعدادات، حيث توجد البيانات التي نحتاجها:
انسخ البيانات والصقها في الحقول المناسبة في إعدادات Mavibot: انتقل إلى قسم "Acquiring" وابحث عن خدمة Paypal:
بعد ذلك، انقر على "Connect" واملأ الحقول بالمفتاح السري وClient ID اللذين حصلت عليهما مسبقًا:
بعد ذلك، انقر على "Save settings". وبذلك يكتمل الاتصال.
How to create a payment link
Using payment_sum variable
لإنشاء رابط دفع، تحتاج إلى تعيين قيمة payment_sum المتغير وبعد ذلك مباشرةً سيظهر المتغير paypal_pay_url .
payment_title
(متغير اختياري) هذا هو اسم المنتج.
إذا لم يتم تحديده، فسيُملأ بالنص: “Invoice payment order_id" (order_id هو معرّف الطلب في mavibot)
payment_description
وصف المنتج، حقل اختياري
company_name
يظهر اسم شركتك في أعلى صفحة الدفع تمامًا (المثال أدناه، الشركة)
بالإضافة إلى ذلك، قبل تحديد payment_sum، يمكنك تحديد اللغة التي ستظهر بها صفحة الدفع.
للقيام بذلك، عيّن المتغير locale. اللغة الافتراضية هي الروسية (ru-RU). الخيارات الممكنة: da-DK، he-IL، id-ID، ja-JP، no-NO، pt-BR، ru-RU، sv-SE، th-TH، zh-CN، zh-HK، zh-TW، إلخ. (تختلف مجموعة اللغات المتاحة، اعتمد على المصدر الأصلي) сысылка первоисточник)
يمكنك أيضًا تحديد العملة التي سيتم قبول الدفع بها. للقيام بذلك، حدّد currency المتغير، الروبل (RUB) مُعيّن افتراضيًا، وللدولار عيّن قيمته إلى USD (currency = USD). يمكن العثور على خيارات العملات الممكنة في الرابط. ссылка ссылке.
والبارامتر الإضافي الثالث هو company_name - اسم شركتك، ويظهر في أعلى صفحة الدفع تمامًا (المثال أدناه، company )
الـ paypal_pay_url يمكن عرض المتغير كرابط أو وضعه على زر بالنص "Pay".
يبدو الرابط كما يلي: https://www.paypal.com/checkoutnow?token=07N53571YM296381N
مثال على التنفيذ.
تعيين مبلغ الدفع واسم الشركة
يرجى الملاحظة: الـ payment_sum يُعيَّن المتغير بالقيمة الأخيرة، بعد المتغيرات الاختيارية payment_title, company_name, إلخ.
بعد ذلك، حدّد المتغير #{paypal_pay_url} في كتلة "Status" الثانية:
يمكن تحديد المتغير في حقل الرسالة:
يمكن تحديد المتغير في حقل url في إعدادات المرفق:
يمكن تحديد المتغير في حقل url في إعدادات الزر:
عند فتح رابط الدفع
باستخدام دالة الحاسبة paypal_payment_url
أنشئ كتلة في منشئ القمع واستخدم paypal_payment_url في الحاسبة، مع تمرير المعلمات اللازمة إليها:
! payment_sum
المعلمة المطلوبة هي مبلغ الدفع.
currency
عملة الدفع الافتراضية هي ‘USD'. تتوفر القائمة الكاملة في الرابط https://developer.paypal.com/docs/api/reference/currency-codes/
payment_title
عنوان الدفع (حتى 127 حرفًا). (إذا أُهمل، فسيُملأ بالنص: “Invoice payment payment_id”, حيث payment_id هو معرّف الطلب في Mavibot)
payment_description
وصف مختصر للدفع (حتى 127 حرفًا)
company_name
معلمة اختيارية، اسم المنظمة/الشركة، إلخ.
locale
تُحدَّد لغة صفحة الدفع كـ en-US، fr-XC، إلخ. افتراضيًا، هي ‘ru-Ru’. القائمة الكاملة متاحة على الرابط https://developer.paypal.com/api/rest/reference/locale-codes/
عندما يتحقق شرط الكتلة، سيتلقى العميل رابط دفع، وسيتم إنشاء متغير العميل paypal_payment_completed بالقيمة False.
url = paypal_payment_url(2500, 'RUB', 'Invoice payment payment_id','payment description', 'organization name', 'ru-Ru')
How to create a recurring payment
لإنشاء والحصول على رابط للدفع عبر المدفوعات المتكررة، تحتاج إلى إنشاء خطة اشتراك في حسابك الشخصي.
اختيار العرض الذي تم إنشاؤه مسبقًا:
بديلًا عن ذلك، اكتب اسم العرض في شريط البحث وانقر على "Create".
اختر نوع الخصم التلقائي Fixed:
Create subscription
اختيار عملة الاشتراك وشروط الخصم:
تنبيه!!
في Mavibot، العملة الافتراضية هي اليورو، وإذا كان الخصم بالدولار أو بعملة أخرى، فعند إنشاء الاشتراك حدّد العملة التي تحتاجها، وفي Mavibot نفس العملة من اشتراك Paypal.
بعد ذلك، فعّل الاشتراك:
بعد الإنشاء، سيكون معرّفه متاحًا، وسنستخدمه لاحقًا لإنشاء اشتراك والحصول على رابط دفع.
يتم إنشاء رابط الدفع وإرجاعه بواسطة الدالة: paypal_subscription_url(plan_id, shipping_currency, shipping_payment_sum, start_time)
! plan_id
معرّف خطة الاشتراك
! shipping_currency
إذا كانت الدفعة للخطة المحددة بالدولار، فلا تحتاج إلى تمرير أي شيء، وإلا فنمرّر رمز العملة الذي حددته في الخطة. يتم تمرير العملة التي يُدفع بها التوصيل هنا (حتى لو كانت التكلفة صفرًا). افتراضيًا، USD
shipping_payment_sum
هذه معلمة اختيارية تحدد تكلفة التوصيل. افتراضيًا، تكون القيمة مضبوطة على صفر.
start_time
معلمة اختيارية، تاريخ ووقت بدء الاشتراك. إذا لم تمرر أي شيء، فإن تاريخ بدء الاشتراك = تاريخ الدفع. التنسيقات: %d.%m.%Y أو %d.%m.%Y %H:%M.
عند إنشاء الرابط، سيظهر أيضًا المتغير paypal_subscription_id ، والذي سيحتوي على معرّف الاشتراك.
أثناء الدفع، ستتلقى callback، وهو مشابه للدفع مقابل عملية دفع عادية.
paypal_subscription_data(paypal_subscription_id) - الحصول على معلومات عن الاشتراك
paypal_subscription_id
معرّف الاشتراك.
الـ النتيجة لتنفيذ الدالة - هي مصفوفة تحتوي على جميع معلومات الاشتراك، بما في ذلك عدد الدفعات، وعدد محاولات الخصم الفاشلة، والحالة، والمزيد.
How to cancel subcription
ستساعد الدالة paypal_remove_subscription(paypal_subscription_id) العملاء على إلغاء اشتراكاتهم في خدماتك.
المعلمات:
paypal_subscription_id
معرّف الاشتراك الذي يتم حفظه في متغير العميل عند الاشتراك.
كيفية معالجة النتيجة
بعد نجاح الدفع، سيتم إرسال callbacks إلى البوت، مما سيتيح لك معرفة أن الدفع كان ناجحًا.
في النظام، ترى callbacks على أنها رسائل من المستخدم، لكن المستخدم نفسه لا يراها: فهي تُعرض للمشغل فقط.
لمعالجة callback في الكتلة وإرسال رسائل للمستخدم عن حالة الدفع، استخدم نوع المقارنة "Exact match".
قد تتأخر callbacks، لذلك بعد عرض رابط الدفع للمستخدم، يُنصح بإرسال رسالة مثل: “بعد إتمام الدفع، يرجى الانتظار حتى تصلك رسالة تأكيد تفيد بأن الدفع تم بنجاح.”
For direct payment
تتكون callback الخاصة بالدفع الناجح من أول 10 أحرف من secret والتوقيع مع الحالة. على سبيل المثال: EHsWHYOoWV_success
المثال 1: التفاعل مع دفع ناجح باستخدام كتلة "Start condition":
المثال 2: التفاعل مع دفع ناجح باستخدام كتلة "Start condition":
إذا كنت لا تريد إخراج المستخدم من تدفق الشات بوت الرئيسي، فاستخدم كتلة “No-state with condition” — لا يمكن إعادة توجيه المستخدمين إلى هذه الكتلة مباشرةً، لذا بعد الدفع الناجح سيبقون مع ذلك في القمع الرئيسي، مع تلقي إشعار بالدفع الناجح أيضًا.
ولكن إذا كنت تريد متابعة القمع بناءً على حدث الدفع الناجح، فاستخدم كتلة “Start condition”. في هذه الحالة، بعد إكمال كتلة الدفع، سيتم تحويل المستخدم إلى كتلة “Start condition”، والتي يمكنك من خلالها مواصلة بناء القمع الخاص بك.
تتوفر معلومات إضافية عن الكتل الشرطية في المقالة التي تحمل الاسم نفسه. блоках с условием рассказали رابط
عند نجاح الدفع، يتم تعيين المتغير paypal_payment_completed إلى True.
بعد اكتمال الدفع، تتم إضافة المتغير paypal_callback_data إلى العميل، والذي يحتوي على بيانات محدثة لنظام الدفع حول حالة العملية. يمكنك استخراج البيانات اللازمة من القاموس المستلم باستخدام طريقة get.
لإجراء دفعة متكررة، تحتاج إلى إعادة تعيين المتغير payment_sum، والمتغير الذي يحتوي على الرابط المُنشأ مسبقًا، ثم إعادة تعيين المتغير payment_sum أو استدعاء الدالة للحصول على رابط جديد.
For subscription payments
تمت إضافة دالة إعداد callback للعمليات المتعلقة بالاشتراكات في 09/01/2024. ولكي تعمل callbacks من هذه الفئة بشكل صحيح، تحتاج إلى تعطيل وربط تكامل نظام دفع Paypal في مشروعك.
عند إجراء دفعة اشتراك، سيتلقى البوت إحدى الرسائل التالية:
حول تفعيل الاشتراك. على سبيل المثال، subscription_I-PTV5H4MRC1H3_activated;
إشعار بنجاح دفعة اشتراك متكررة. على سبيل المثال، subscription_I-PTV5H4MRC1H3_paid;
أو حول خطأ في دفع الاشتراك. على سبيل المثال، subscription_I-PTV5H4MRC1H3_not_paid;
في الأمثلة أعلاه، “I-PTV5H4MRC1H3” هو معرّف اشتراك العميل، والذي يمكن الوصول إليه باستخدام متغير paypal_subscription_id.
ستضيف callback المتغير paypal_subscription_callback_data إلى العميل، والذي يحتوي على بيانات حالية لنظام الدفع حول حالة العملية. يمكنك استخراج البيانات اللازمة من القاموس المستلم باستخدام طريقة get.
المثال 1: التفاعل مع تفعيل الاشتراك باستخدام كتلة "Start condition":
المثال 1: التفاعل مع تفعيل الاشتراك باستخدام كتلة "Not state with condition":
آخر تحديث