باي بال (PayPal)
يتيح باي بال للمشترين الدوليين الدفع من رصيدهم أو ببطاقاتهم. تستخدم TakeTheme واجهة باي بال REST: يوافق المشتري على الدفع لدى باي بال، ثم تُحصَّل الأموال مباشرة بعد ذلك.
الربط
الإعدادات ← المدفوعات ← باي بال.
| البيانات | مطلوبة | من أين تحصل عليها |
|---|---|---|
| معرّف العميل (Client ID) | نعم | لوحة مطوّري باي بال ← تطبيقك |
| السر (Client Secret) | نعم | التطبيق نفسه |
| معرّف الويب هوك (Webhook ID) | — | يُنشأ عند تسجيل ويب هوك في باي بال، ويلزم للتحقق من التواقيع |
| الإعداد | الافتراضي | الوظيفة |
|---|---|---|
| البيئة | sandbox | sandbox للاختبار وlive للمدفوعات الحقيقية |
| إرسال بريد تأكيد الدفع | مفعّل | يرسل بريدًا للعميل عند نجاح الدفع |
| التنبيه عند فشل الدفع (عناوين بريد) | فارغ | ينبّه فريقك عند فشل عملية دفع |
| تعليم الطلبات كمدفوعة تلقائيًا | مفعّل | غير مُفعَّل حاليًا — أي دفع مؤكَّد يجعل الطلب مدفوعًا على أي حال |
بيانات الاختبار تعمل مع sandbox فقط، وبيانات الإنتاج مع live فقط. وتبديل البيئة دون تبديل البيانات يجعل كل عمليات الدفع تفشل. تذكّر تحويلها إلى live قبل الإطلاق — فالقيمة الافتراضية هي بيئة الاختبار.
مسار الدفع
يُؤكَّد الدفع في باي بال عبر مسارين مستقلين، ولهذا فهو أكثر البوابات مرونة:
- الويب هوك — يرسل باي بال إلى
POST /v1/webhooks/paypal. الأحداث المعالَجة: الموافقة على الطلب، اكتمال التحصيل، رفض التحصيل، واسترداد التحصيل. - رابط العودة — عند عودة المشتري إلى متجرك، تسأل TakeTheme باي بال مباشرة عن حالة الطلب. وإذا كان مُوافقًا عليه ولم يُحصَّل بعد، تُحصّله في تلك اللحظة وتُنشئ الطلب.
يفوز المسار الذي يصل أولًا، ويصبح الآخر بلا أثر. ولا يمكن أن يسجّل تحصيل مكرر عملية ثانية، ولا يُنشأ الطلب إلا مرة واحدة.
سجّل الويب هوك في باي بال والصق معرّفه الناتج في نموذج بيانات الاعتماد. بدونه لا يمكن التحقق من تواقيع الويب هوك — وستظل الطلبات تصل عبر مسار العودة، لكنك تفقد مسار التأكيد الخاص بالمشترين الذين يغلقون الصفحة قبل التحويل.
الاسترداد
الاسترداد في TakeTheme يسجّل العملية محليًا، ولا يستدعي واجهة الاسترداد لدى باي بال. نفّذ الاسترداد من حسابك في باي بال ثم سجّله على الطلب.
لكن TakeTheme تستمع لحدث PAYMENT.CAPTURE.REFUNDED من باي بال، لذا يُسجَّل أي استرداد تنفّذه هناك على سجل الدفع.
حل المشكلات
الدفع يعمل في الاختبار ويفشل بعد الإطلاق.
إعداد البيئة ما زال sandbox، أو أنك بدّلت أحد البيانات دون البقية.
بعض الطلبات تظهر متأخرة. هذا مسار رابط العودة وهو ينفّذ التحصيل عند تحويل المشتري بدل الويب هوك. سجّل ويب هوك واحفظ معرّفه للحصول على المسار الأسرع.
استرداد نفّذته في باي بال لا ينعكس على الطلب. تأكد من تسجيل الويب هوك وحفظ معرّفه — فهذا الحدث هو الطريقة التي تعرف بها TakeTheme بالاستردادات المنفَّذة خارج لوحة التحكم.