كيف تربط ماي فاتورة بموقعك وتطبيقك في الكويت

ماي فاتورة (MyFatoorah) شركة دفع إلكتروني كويتية يدرجها بنك الكويت المركزي ضمن مقدمي خدمات النقود الإلكترونية، ويستخدمها التجار لتحصيل المدفوعات عبر كي نت والبطاقات وApple Pay، ولإرسال روابط الفواتير إلى العملاء. في هذا الدليل عن ماي فاتورة الكويت نجيب عمّا يسأل عنه التاجر والمبرمج: هل ماي فاتورة مرخصة؟ كيف تفتح حساباً وتفعّله؟ ما طرق الربط المتاحة؟ وكيف تربطها بموقع Next.js أو تطبيق React Native (Expo)، وترسل روابط الدفع على واتساب؟

هذا دليل تقني مبني على وثائق ماي فاتورة المنشورة، وقد راجعناها في 27 سبتمبر 2026. وهو ليس استشارة قانونية أو مالية، فتأكّد من الرسوم وطرق الدفع المفعّلة مع ماي فاتورة مباشرة قبل الإطلاق.

هل ماي فاتورة مرخصة من البنك المركزي؟

حتى 27 سبتمبر 2026، نعم. ينشر بنك الكويت المركزي سجلاً لمقدمي خدمات النقود الإلكترونية، ويرد فيه اسم شركة ماي فاتورة لتقديم خدمات الدفع الإلكتروني بنوع خدمة مقدم خدمات النقود الإلكترونية الكبيرة. وبحسب السجل، عنوان الشركة في منطقة شرق، وهاتفها 1888805، وبريد الدعم supportkwt@myfatoorah.com.

ملاحظتان قبل توقيع العقد:

• بوابات الدفع الأخرى في الكويت قد تكون مرخصة ضمن فئة مختلفة لدى البنك المركزي، فابحث عن كل شركة باسمها في موقع البنك ولا تفترض. دليلنا عن بوابات الدفع الإلكتروني في الكويت يعرض الصورة كاملة.
• عند مراجعتنا في 27 سبتمبر 2026، كان أسفل النسخة الإنجليزية من موقع ماي فاتورة يذكر شركة "Fatoorah for electronic marketing" المرخصة من البنك المركزي السعودي (ساما) بالترخيص رقم 21/LLC/1444. إذا كان نشاطك في الكويت فتأكد أن عقدك مع الكيان الكويتي المدرج في سجل بنك الكويت المركزي.

ماذا تقدم ماي فاتورة؟

تقول ماي فاتورة إنها تستقبل المدفوعات في ثماني دول: الكويت والسعودية والإمارات وقطر والبحرين وعُمان ومصر والأردن. وهذه أهم خدماتها لمن يخطط لمشروع:

قائمة طرق الدفع في الوثائق تشمل كي نت وفيزا وماستركارد وأميكس وApple Pay وGoogle Pay وSamsung Pay وSTC Pay، إضافة إلى طرق دفع لأسواق أخرى مثل بنفت ومدى وميزة. لكن الصفحة نفسها تذكر أن الطرق المتاحة تختلف حسب حسابك واتفاقك مع ماي فاتورة، فاطلب قائمة الطرق المفعّلة لحسابك كتابياً. وللتفاصيل الخاصة بكي نت راجع دليل ربط كي نت.

كيف تفتح حساب تاجر في ماي فاتورة؟

1. سجّل حساباً جديداً في register.myfatoorah.com واختر دولتك.
2. تواصل مع مدير الحساب أو مندوب المبيعات في ماي فاتورة لتفعيل الحساب وتفعيل صلاحية API التي يحتاجها الربط.
3. اطلب في الوقت نفسه ما تحتاجه من خصائص إضافية، مثل حفظ البطاقات أو الشحن أو تعدد الموردين، واطلب قائمة طرق الدفع المفعّلة وجدول الرسوم كتابياً.
4. إلى أن يُفعَّل الحساب، ابنِ الربط واختبره على بيئة التجربة بالمفتاح التجريبي العام.

ويخدم الحساب الواحد أكثر من دولة من دول ماي فاتورة، فلا تحتاج حساباً جديداً لكل دولة، بل تطلب من مدير حسابك إضافة الدولة.

أي طريقة ربط تختار؟

توثّق ماي فاتورة ثلاث طرق تناسب أغلب التجار، وطريقة رابعة لمن يملك شهادة PCI:

بحسب الوثائق، الدفع المضمّن يعالج البطاقات وApple Pay وGoogle Pay وSTC Pay داخل صفحتك، أما بقية الطرق المفعّلة ومنها كي نت فتنتقل إلى الصفحة المستضافة. لذلك صفحة الدفع المعتادة في الكويت خليط: بطاقات ومحافظ داخل الصفحة، وكي نت عبر التحويل.

وتفعيل Apple Pay في الدفع المضمّن يحتاج توثيق نطاق موقعك أولاً، وللصورة الكاملة راجع دليل ربط Apple Pay.

بيئة التجربة ومفاتيح API

كل طلب يحمل الترويسة Authorization: Bearer <المفتاح>. وهذه العناوين كما في صفحة مفتاح API:

للتجربة طريقان: مفتاح تجريبي عام منشور في صفحة مفتاح API، أو حساب تجريبي تسجله في registertest.myfatoorah.com مع اختيار الكويت وتخطي بيانات البنك، ثم تراسل tech@myfatoorah.com لتفعيله.

أما مفاتيح التشغيل الفعلي (Live) فينشئها الحساب الرئيسي (Super Master Account) من لوحة التحكم عبر إعدادات الربط ثم مفتاح API، ولكل مفتاح اسم وتاريخ انتهاء وحالة تفعيل وصلاحيات محددة. انتبه لهذه النقاط:

• الحد الأقصى 5 مفاتيح، فخطط لتدوير المفاتيح بدل إنشاء مفتاح لكل مبرمج.
• لكل دولة مفعّلة مفتاح خاص بها، واستخدامه هو ما يتيح للعميل الدفع بعملة بلده.
• تعطيل المستخدم الذي أنشأ المفتاح يعطّل المفتاح نفسه، فأنشئ المفاتيح من مستخدم رئيسي مخصص لهذا الغرض لا يُعطَّل عند مغادرة موظف.
• المفتاح الذي ينقصه الإذن المطلوب يُعيد خطأ 401، فأعطِ كل مفتاح أقل صلاحيات يحتاجها.

بطاقات الاختبار في ماي فاتورة

تنشر ماي فاتورة صفحة بطاقات الاختبار لكل طريقة دفع. وعند مراجعتنا في 27 سبتمبر 2026 كانت تتضمن بطاقة كي نت يحدد تاريخ انتهائها هل تكون النتيجة Captured أو Not Captured فتختبر الحالتين، وعدة بطاقات فيزا وماستركارد تُستخدم مع أي اسم من كلمتين. ولا توجد بطاقة من ماي فاتورة لـ Apple Pay، فاستخدم بطاقات Apple التجريبية. انسخ القيم من الصفحة يوم الاختبار لأنها قد تتغير.

وتنبّه الصفحة إلى أن بيئة اختبار كي نت غير متاحة في كل الدول، فاختبر كي نت على حساب تجريبي مسجل في الكويت.

خطوات الدفع في الإصدار الثالث

الوثائق تطلب استخدام نقاط /v3، وتذكر أن /v2 لا يُستخدم في أي ربط جديد. والدروس القديمة على الإنترنت ما زالت تستخدم أسماء مثل SendPayment. أما مسار الإصدار الثالث فهو:

1. POST /v3/sessions لإنشاء جلسة دفع مضمّن، جلسة واحدة لكل عملية، والرد يحمل SessionId وEncryptionKey.
2. POST /v3/payments لإنشاء عملية دفع أو فاتورة، والرد يحمل InvoiceId ورابط PaymentURL.
3. بعد الدفع تعيد ماي فاتورة العميل إلى رابط العودة عندك ومعه paymentId.
4. GET /v3/payments/{paymentId} يُعيد تفاصيل الفاتورة والعملية والمبلغ، وتكون الفاتورة PAID إذا نجحت إحدى عملياتها بحالة SUCCESS.

وهذه أكثر الحقول استخداماً في POST /v3/payments:

الربط مع موقع Next.js

هذا الهيكل الذي نعتمده في مشاريع Next.js: المفتاح يبقى على الخادم، ولا نثق بأي نتيجة تأتي من المتصفح.

1. احفظ المفتاح في متغيرات البيئة على الخادم، ولا تضع قبله البادئة NEXT_PUBLIC_ لأنها ترسله إلى المتصفح.
2. أنشئ الطلب في قاعدة بياناتك أولاً برقمك أنت وحالة "بانتظار الدفع".
3. من Route Handler مثل app/api/checkout/route.ts استدعِ POST /v3/sessions للدفع المضمّن، أو POST /v3/payments للصفحة المستضافة أو رابط الفاتورة، وأعِد إلى المتصفح SessionId أو PaymentURL فقط.
4. حمّل ملف session.js في صفحة الدفع وحدها، من demo.myfatoorah.com للتجربة أو portal.myfatoorah.com للتشغيل الفعلي في الكويت، ثم استدعِ myfatoorah.init. هكذا تبقى بقية صفحات الموقع سريعة.
5. القيمة paymentCompleted: true في الـ callback تعني انتهاء خطوات الدفع فقط، لا نجاحه. فك تشفير بيانات الرد بمفتاح EncryptionKey كما في الوثائق، أو انتظر إشعار الخادم.
6. في صفحة النتيجة يقرأ الخادم paymentId ويستعلم عن الحالة، ويتأكد أن الفاتورة PAID وأن المبلغ يطابق الطلب.
7. أضف مساراً لإشعار الخادم (Webhook) يتحقق من التوقيع، ويحدّث الطلب إن لم يكن مدفوعاً، ثم يرد بـ HTTP 200.

الربط مع تطبيق React Native (Expo)

تذكر صفحة حزم التطوير لدى ماي فاتورة حزماً لـ iOS وAndroid وFlutter وReact Native وCordova. وفي تطبيق مبني بـ Expo (React Native) نعتمد هذا الهيكل:

1. إنشاء الدفع من الخادم. يستدعي التطبيق واجهتك أنت، وهي تستدعي POST /v3/payments بالمفتاح المحفوظ على الخادم، وتعيد رابط PaymentURL فقط. لا يوضع مفتاح التشغيل الفعلي داخل التطبيق.
2. فتح صفحة الدفع في متصفح داخل التطبيق. استخدم expo-web-browser مع رابط PaymentURL. وهذا يشمل كي نت، لأنه ينتقل إلى الصفحة المستضافة في كل طرق الربط.
3. العودة عبر رابط عميق. اجعل IntegrationUrls.Redirection صفحة على نطاقك تعيد paymentId إلى التطبيق عبر Universal Link أو مخطط الروابط الخاص بتطبيقك.
4. التأكيد من الخادم. عند عودة التطبيق إلى الواجهة يسأل خادمك عن حالة الطلب، ويعتمد الخادم على إشعار Webhook واستعلام GET /v3/payments/{paymentId}، لا على صفحة العودة وحدها.
5. حقول البطاقة داخل التطبيق اختيارية. لنموذج البطاقة الأصلي أو Apple Pay المضمّن استخدم حزمة React Native من ماي فاتورة. والحزم الأصلية تعمل في نسخة تطوير من Expo (Development Build) لا في Expo Go. وإذا احتاجت الحزمة مفتاح API داخل التطبيق فاعتبره مكشوفاً: أنشئ له مفتاحاً مستقلاً بأقل الصلاحيات وتاريخ انتهاء.

بديل Flutter. إذا كان تطبيقك مبنياً بـ Flutter، فماي فاتورة توفر حزمة myfatoorah_flutter. وبحسب دليلها تبدأ بـ MFSDK.init(apiKey, MFCountry.KUWAIT, MFEnvironment.TEST)، وتستخدم initiateSession() وMFPaymentCardView لحقول البطاقة داخل التطبيق، ثم initiatePayment وexecutePayment لطرق التحويل مثل كي نت. مثال الدليل يكتب رقم طريقة كي نت مباشرة، والأسلم أن تقرأ الأرقام من الرد. وتنطبق قاعدة التأكيد من الخادم نفسها. وإن كنت ما زلت تختار تقنية برمجة التطبيق فراجع مقارنة Flutter أم React Native.

روابط الدفع والفواتير على واتساب

تسوّق ماي فاتورة في موقعها لإرسال الفواتير عبر واتساب والبريد الإلكتروني وSMS. وفي واجهة API تُنشأ الفاتورة عبر POST /v3/payments دون تحديد طريقة الدفع، مع خيار الإرسال NotificationOption:

ولإرسال الرابط من رقم واتساب بزنس الخاص بشركتك، اطلب خيار LINK وأرسل رابط PaymentURL بنفسك:

1. يؤكد العميل الطلب في المحادثة.
2. ينشئ نظامك الفاتورة بخيار LINK ويحفظ InvoiceId مع الطلب.
3. يرسل الموظف أو الرد الآلي رابط الدفع في المحادثة.
4. يصل إشعار الخادم فيتحدث الطلب إلى مدفوع، ويرسل النظام التأكيد في المحادثة نفسها.

مثال افتراضي: عيادة تأخذ عربوناً قبل كل موعد، ترسل الرابط لحظة الاتفاق على الموعد، ويتأكد الحجز تلقائياً دون أن يفتح أحد لوحة التحكم. وحدّد PaymentExpiry حتى لا يبقى رابط غير مدفوع مفتوحاً بلا نهاية. وقواعد واتساب للرسائل التي تبدأها الشركة تبقى سارية؛ راجع دليل ربط واتساب بزنس API.

ومنصة Waslo، منصة الرسائل الخاصة بركن، تتعامل مع هذا النوع من البيع عبر المحادثة: وكيل ذكاء اصطناعي يجيب من قاعدة معرفة الشركة بالعربية والإنجليزية، ويأخذ الطلب، ويرسل في المحادثة رابط دفع من حساب الشركة نفسها لدى بوابة دفع مرخصة، وتُسوّى المبالغ مباشرة للشركة ولا تمر عبر ركن. ويحوّل المحادثة إلى موظف عند الحاجة.

إشعار الخادم (Webhook) وحالة الدفع

إرشادات ماي فاتورة لتحديث حالة الدفع تستحق الالتزام بها:

• صفحة العودة غير مضمونة: تفشل إذا أغلق العميل الصفحة أو كانت الشبكة بطيئة.
• إشعار الخادم (Webhook) يصل غالباً أولاً لأنه من خادم إلى خادم. فعّل المفتاح السري (Secure Key) من صفحة الـ Webhook في لوحة التحكم ليحمل كل إشعار ترويسة MyFatoorah-Signature، ثم أعد حساب التوقيع (HMAC SHA-256 على الحقول الموثقة مرتبة بصيغة key=value، والقيم الفارغة نصاً فارغاً، ثم Base64) وقارنه قبل تحديث الطلب والرد بـ HTTP 200.
• التكرار وارد: في حالات نادرة ترسل بعض طرق الدفع، ومنها كي نت، أكثر من إشعار للعملية نفسها. وحالة SUCCESS تتقدم على أي حالة أخرى حتى لو وصلت بعدها، وهي حالة نهائية. لذلك اجعل المعالجة آمنة عند التكرار.
• إعادة المحاولة: في Webhook V2 تحدد عدد المحاولات والفاصل بينها من لوحة التحكم.
• عند تعذر الاستعلام: توصي الوثائق بثلاث محاولات بفاصل 5 ثوانٍ ومهلة لا تقل عن 30 ثانية، ثم وضع الطلب في حالة انتظار لمعالجته لاحقاً.
• حد الطلبات: نقطة الاستعلام لها حد، وإن توقعت ضغطاً عالياً فاطلب رفعه من مدير حسابك.

كم رسوم ماي فاتورة؟

حتى 27 سبتمبر 2026 لم نجد جدول رسوم للعمليات في الكويت على موقع ماي فاتورة، وتذكر ماي فاتورة في صفحة الأسئلة الشائعة أن الرسوم تختلف حسب نوع النشاط وحجم العمليات وعوامل أخرى، وتدعو التاجر إلى طلب عرض سعر خاص. لذلك اطلب جدول الرسوم مكتوباً لكل طريقة دفع قبل الإطلاق.

والمفيد تقنياً أن رد تفاصيل الدفع يحمل رسوم الخدمة (ServiceCharge) وضريبتها (ServiceChargeVAT) والمبلغ الذي ستستلمه (ReceivableAmount)، فاحفظها مع كل عملية لتصبح مطابقة التسويات استعلاماً بسيطاً.

تغيير بوابة الدفع لاحقاً

اجعل رقم الطلب رقمك أنت، واحفظ InvoiceId وPaymentId بجانبه، واعزل البوابة في طبقة مستقلة حتى لا يعرف نقاط ماي فاتورة إلا جزء واحد من النظام. واسترداد المبالغ السابقة يبقى عبر البوابة التي حصّلتها. ولمزودي الدفع المرخصين الآخرين راجع دليل بوابات الدفع الإلكتروني في الكويت ودليل ربط تاب.

كيف تنفذ ركن ربط ماي فاتورة؟

إذا كان متجرك أو تطبيقك مبرمجاً خصيصاً، فنحن في ركن ننفذ الربط كاملاً: دفع من الخادم، وإشعارات موقّعة، وصفحات نتيجة بالعربية والإنجليزية، وحقول جاهزة للمطابقة، في الموقع وفي تطبيقات React Native (Expo)، ضمن خدمة تصميم وبرمجة المواقع. تبدأ المواقع من 799 ديناراً كويتياً، والتطبيقات من 1,999 ديناراً كويتياً، والسعر النهائي يعتمد على نطاق العمل.