ماي فاتورة (MyFatoorah)
م اي فاتورة صفحة دفع مستضافة تُستخدم في الكويت والسعودية والإمارات وقطر والبحرين وعُمان والأردن ومصر. يدفع المشترون على صفحة ماي فاتورة — بطاقات وكي نت ومدى وأبل باي وغيرها من الطرق المفعّلة على حسابك في ماي فاتورة — ثم يعودون إلى متجرك. الطرق التي تظهر يحددها حسابك في ماي فاتورة وليس TakeTheme.
الربط
الإعدادات ← المدفوعات ← ماي فاتورة.
| بيان الاعتماد | مطلوب | أين تجده |
|---|---|---|
| مفتاح API | نعم | بوابة ماي فاتورة ← إعدادات التكامل ← مفتاح API |
| الدولة | نعم | الدولة التي فُتح فيها حسابك في ماي فاتورة — المفتاح يعمل فقط على خادم تلك الدولة. الخيار kuwait يشمل أيضاً البحرين والأردن وعُمان. اختر test فقط مع مفتاح تجريبي |
| المفتاح السري للـ Webhook | لا | بوابة ماي فاتورة ← إعدادات التكامل ← إعدادات Webhook (الإصدار V2). راجع أدناه |
تُنشأ الطلبات عند عودة المشتري من ماي فاتورة: تستعلم TakeTheme عن الدفع لدى ماي فاتورة أثناء العودة، لذا لا يلزم تسجيل أي شيء في المسار المعتاد. كما تطلب TakeTheme من ماي فاتورة إرسال Webhook لكل عملية دفع تلقائياً، فيُنشأ الطلب إذا دفع المشتري ثم أغلق الصفحة.
إذا فعّلت Webhook من الإصدار V2 بمفتاح سري في بوابة ماي فاتورة، ألصق هذا المفتاح في المفتاح السري للـ Webhook ليتم التحقق من توقيع كل إشعار.
استخدم الدولة test مع مفتاح تجريبي من registertest.myfatoorah.com لتجربة المسار دون أموال حقيقية.
الإعدادات
| الإعداد | الافتراضي | وظيفته |
|---|---|---|
| اسم الدفع في صفحة الدفع | فارغ | الاسم الذي يراه العميل (مثل "بطاقة أو كي نت أو أبل باي"). إن تُرك فارغاً يظهر "MyFatoorah" |
| رسوم المعاملة | لا يوجد | رسوم ثابتة أو نسبية تُضاف إلى الطلب عند اختيار هذه الطريقة |
| خصم الدفع | لا يوجد | خصم يُطبَّق عند اختيار المشتري لهذه الطريقة |
| إرسال بريد تأكيد الدفع | مفعّل | يرسل بريداً للعميل عند نجاح الدفع |
| إشعار عند فشل الدفع (بريد) | فارغ | ينبّه فريقك عند فشل عملية دفع |
العملة
تُنشئ TakeTheme فاتورة ماي فاتورة بـعملة متجرك، وتحوّلها ماي فاتورة إلى عملة التسوية في حسابك. توثّق ماي فاتورة العملات SAR وBHD وAED وQAR وOMR وKWD وJOD وEGP؛ وإذا كانت عملة متجرك غير مقبولة في حسابك يعرض الدفع رسالة الخطأ من ماي فاتورة بدلاً من رابط الدفع.
إذا أبلغت ماي فاتورة عن مبلغ مدفوع يختلف عن إجمالي الطلب، تسجّل TakeTheme الفرق للمطابقة دون رفض الدفع.
مسار الدفع
- يختار المشتري ماي فاتورة ويُرسل الطلب.
- تُنشئ TakeTheme فاتورة في ماي فاتورة (بمرجع داخلي) وتوجّه المشتري إلى صفحتها.
- يدفع المشتري بأي طريقة يوفرها حسابك.
- تعيد ماي فاتورة المشتري إلى TakeTheme (
GET /v1/payment/myfatoorah/return/<reference>?paymentId=…). تقرأ TakeTheme ذلك الدفع من ماي فاتورة بمفتاح API الخاص بك وتتأكد أنه يخص عملية الدفع هذه بالذات — فلا يُعتبر ما رآه المشتري على الصفحة دليلاً — ثم تُنشئ الطلب مدفوعاً. - يصل المشتري إلى صفحة الشكر في متجرك.
ترسل ماي فاتورة أيضاً Webhook:
POST https://<your-api-host>/api/v1/payment/webhook/myfatoorah
لا يحدد الـ Webhook النتيجة بمفرده: هو فقط يخبر TakeTheme أي دفع تستعلم عنه، وتُعاد قراءة الحالة من ماي فاتورة. إذا ضبطت المفتاح السري للـ Webhook يُرفض أي إشعار بلا توقيع أو بتوقيع غير مطابق بالرمز 403. أيهما وصل أولاً (العودة أو الـ Webhook) ينشئ الطلب — ولا يُنشئان طلبين.
المدفوعات الفاشلة والمتروكة
الدفع المرفوض يعيد المشتري بنتيجة فاشلة فيرى فشل الدفع ويمكنه المحاولة مجدداً. تتيح ماي فاتورة للمشتري إعادة المحاولة على الفاتورة نفسها، لذا تُسجَّل المحاولة الفاشلة لكن أي محاولة ناجحة لاحقة على الفاتورة نفسها تُنشئ الطلب. الفاتورة التي لا تُدفع لا تُنشئ طلباً.
الاسترداد
عمليات الاسترداد تُسجَّل في TakeTheme فقط — لا يصل أي طلب استرداد إلى ماي فاتورة. نفّذ الاسترداد من بوابة ماي فاتورة ثم سجّله هنا. ر اجع الاسترداد.
استكشاف الأخطاء
يقول الدفع إن ماي فاتورة رفضت مفتاح API. المفتاح والـدولة غير متطابقين — المفتاح يعمل فقط على خادم الدولة التي فُتح فيها حسابه. أعد اختيار الدولة أو ألصق مفتاحاً جديداً (القيم المقنّعة تُتجاهل عند الحفظ).
دفع المشتري لكن لم يظهر طلب.
افتح سجل الدفع للطلب: إذا تعذّر الوصول إلى ماي فاتورة أثناء الاستعلام، يواصل المتجر المحاولة ويظهر الطلب بمجرد النجاح. وإذا ضبطت مفتاحاً سرياً للـ Webhook فإن ظهور 403 في سجل الـ Webhook يعني أن المفتاح المخزَّن لا يطابق الموجود في بوابة ماي فاتورة.
طريقة دفع غير ظاهرة في صفحة ماي فاتورة. تُفعَّل الطرق لكل حساب لدى ماي فاتورة؛ ولا ترسل TakeTheme أي تصفية للطرق.