تكامل سترايب مع أودو: الدليل الكامل للإعداد للشركات في الإمارات

يُعدّ Stripe من أنظف الوسائل لقبول مدفوعات البطاقات في نظام أودو (Odoo)؛ فهو يدعم بطاقات Visa وMastercard وخدمتي Apple Pay وGoogle Pay مباشرةً دون أي إضافات، ويسوّي المبالغ بالدرهم الإماراتي، ويُبقي العميل في صفحة الدفع الخاصة بمتجرك بدلاً من تحويله إلى صفحة مصرفية خارجية كما تفعل بوابات التحويل البنكي المُلحقة. وعبر مشاريع التنفيذ التي نديرها في أوكلاند، يبقى Stripe مزوّد الدفع الذي نلجأ إليه في أغلب الحالات عندما ترغب شركة إماراتية في قبول مدفوعات البطاقات عبر الإنترنت دون عناء الصفحات المصرفية المستضافة. يأخذك هذا الدليل خطوة بخطوة عبر الإعداد الكامل لإصدارات أودو الحديثة (16 و17 و18)، بما فيها الأجزاء التي تتجاوزها معظم الشروحات: الويب هوك (Webhook)، والانتقال من بيئة الاختبار إلى التشغيل الفعلي، وكيفية ارتباط الدفعة بفواتيرك المتوافقة مع ضريبة القيمة المضافة.

قبل أن تبدأ: المتطلبات الأساسية

إنجاز هذا الإعداد بشكل صحيح من المرة الأولى يعني تجهيز بعض الأمور قبل أن تفتح شاشة الإعدادات في أودو.

• حساب Stripe مفعّل. بالنسبة للمنشآت الإماراتية، يتيح Stripe فتح الحساب باستخدام الرخصة التجارية والهوية الإماراتية للمفوّض بالتوقيع وحساب مصرفي باسم الشركة لاستلام التحويلات بالدرهم. أكمل عملية التحقق من الحساب حتى نهايتها، إذ تبقى التحويلات معلّقة إلى أن يتأكد Stripe من مستندات منشأتك.
• نسخة أودو مع التطبيقات المناسبة. للبيع عبر الإنترنت، ثبّت تطبيقي الموقع الإلكتروني (Website) والتجارة الإلكترونية (eCommerce). ولروابط دفع الفواتير والاشتراكات، ثبّت تطبيق المحاسبة (أو الفوترة)، وإذا كنت تُصدر فواتير لخطط دورية فأضف تطبيق الاشتراكات (Subscriptions).
• عملة الشركة وضريبة القيمة المضافة مهيأتان بشكل صحيح. اضبط عملة الشركة على الدرهم الإماراتي، وتأكد من إدخال ضريبة القيمة المضافة بنسبة 5% ورقم التسجيل الضريبي (TRN) في إعدادات الشركة، حتى تتحول الطلبات المدفوعة عبر Stripe إلى فواتير نظيفة وجاهزة لمتطلبات الهيئة الاتحادية للضرائب (FTA).
• بروتوكول HTTPS مفعّل على نطاقك. لن يعالج Stripe بيانات البطاقات الفعلية عبر اتصال غير مؤمّن، كما يتطلب الويب هوك نقطة اتصال عامة تعمل عبر HTTPS. تتولى منصتا Odoo Online وOdoo.sh ذلك تلقائياً؛ أما على الخوادم المستضافة ذاتياً فتأكد من صلاحية شهادة SSL لديك.

الخطوة 1 — تفعيل مزوّد الدفع Stripe في أودو

يأتي Stripe ضمن مزوّدي الدفع المدمجين في أودو، فلا حاجة لتنزيل أي شيء من متجر التطبيقات. انتقل إلى تطبيق المحاسبة (أو الموقع الإلكتروني) وافتح قائمة الإعدادات.

1. اذهب إلى المحاسبة ← الإعدادات ← مزوّدو الدفع (وفي تطبيق الموقع الإلكتروني: الإعدادات ← التجارة الإلكترونية ← مزوّدو الدفع).
2. افتح بطاقة Stripe وحدّد حالتها (State). استخدم وضع الاختبار (Test mode) أثناء الإعداد والتحقق، ولا تنتقل إلى وضع التفعيل (Enabled) إلا عند الإطلاق الفعلي.
3. لاحظ أن أودو يوفر في بعض المناطق خاصية الربط بنقرة واحدة "Connect Stripe"، لكننا نوصي بطريقة إدخال بيانات الاعتماد يدوياً الموضحة أدناه لضمان التحكم الكامل في المفاتيح والبيئات.

الخطوة 2 — الحصول على مفاتيح API من Stripe

يتحقق أودو من هويته لدى Stripe عبر مفتاحين: المفتاح القابل للنشر (Publishable key) الذي يستخدمه المتصفح، والمفتاح السري (Secret key) الذي يُستخدم على مستوى الخادم. ولكل منهما نسختان، واحدة للاختبار وأخرى للتشغيل الفعلي، والخلط بينهما هو السبب الأكثر شيوعاً على الإطلاق لتعطل التكامل.

1. سجّل الدخول إلى لوحة تحكم Stripe وافتح Developers ← API keys.
2. فعّل وضع الاختبار (Test mode) في لوحة التحكم وانسخ المفتاح القابل للنشر (يبدأ بـ pk_test_) والمفتاح السري (يبدأ بـ sk_test_).
3. في أودو، افتح مزوّد الدفع Stripe والصق المفتاحين في تبويب بيانات الاعتماد (Credentials)، ثم احفظ.

تعامل مع المفتاح السري كما تتعامل مع كلمة المرور. لا تلصقه أبداً في قالب واجهة أمامية أو مستند عام أو تذكرة دعم فني — فأي شخص يحصل عليه يستطيع تنفيذ عمليات خصم على حسابك.

الخطوة 3 — إعداد الويب هوك (Webhook)

الويب هوك هو الجزء الذي يؤدي إهماله إلى تعطل التكامل بصمت. فهو يتيح لـ Stripe إخطار أودو بشكل غير متزامن عند نجاح الدفعة أو فشلها أو الاعتراض عليها — وهو أمر جوهري في تدفقات المصادقة 3D Secure، ووسائل الدفع المؤجلة، وتجديدات الاشتراكات الدورية التي تتم بينما العميل لم يعد على الصفحة أصلاً.

1. في لوحة تحكم Stripe، انتقل إلى Developers ← Webhooks ← Add endpoint.
2. اضبط عنوان نقطة الاتصال على نطاق أودو الخاص بك متبوعاً بمسار الويب هوك الخاص بـ Stripe: https://yourdomain.com/payment/stripe/webhook
3. اشترك في الأحداث التي يتوقعها أودو — كحد أدنى checkout.session.completed وpayment_intent.succeeded؛ وأضف payment_intent.payment_failed وأحداث الفواتير إذا كنت تشغّل اشتراكات.
4. انسخ سر التوقيع (Signing secret) الناتج — يبدأ بـ whsec_ — وألصقه في حقل توقيع الويب هوك (Webhook Signature) في مزوّد Stripe داخل أودو. بهذا يتحقق أودو من أن الاستدعاءات الواردة صادرة فعلاً عن Stripe.

في إصدارات أودو الحديثة يمكن لخاصية الربط بنقرة واحدة إنشاء هذا الويب هوك تلقائياً، أما إذا أدخلت المفاتيح يدوياً فعليك إنشاؤه بنفسك. وتأكد دائماً من حفظ سر التوقيع — فغيابه يعني أن أودو سيتجاهل الاستدعاءات دون أي تنبيه.

الخطوة 4 — اختبار التكامل

بعد إدخال مفاتيح الاختبار وضبط المزوّد على وضع الاختبار، نفّذ معاملة كاملة قبل أن يصل أي عميل حقيقي إلى صفحة الدفع. يوفر Stripe أرقام بطاقات اختبارية تحاكي جميع النتائج المحتملة.

• دفعة ناجحة: البطاقة 4242 4242 4242 4242، مع أي تاريخ انتهاء مستقبلي، وأي رمز CVC من ثلاث خانات، وأي رمز بريدي.
• مصادقة 3D Secure مطلوبة: البطاقة 4000 0027 6000 3184، للتأكد من أن إعادة التوجيه الخاصة بالمصادقة الآمنة للعميل تكتمل وتعود إلى أودو بسلاسة.
• دفعة مرفوضة: البطاقة 4000 0000 0000 0002، للتحقق من أن أودو يعرض الرفض بشكل لائق ولا يؤكد الطلب.

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

الخطوة 5 — الانتقال إلى التشغيل الفعلي

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

1. في لوحة تحكم Stripe، أوقف وضع الاختبار وانسخ مفتاحيك الفعليين: القابل للنشر (pk_live_) والسري (sk_live_).
2. استبدل مفاتيح الاختبار في أودو بالمفاتيح الفعلية، ثم اضبط حالة مزوّد Stripe على مفعّل (Enabled).
3. أنشئ نقطة اتصال ويب هوك فعلية جديدة تشير إلى المسار نفسه (/payment/stripe/webhook)، وحدّث سر التوقيع في أودو بقيمة whsec_ الفعلية.
4. نفّذ عملية شراء حقيقية صغيرة ببطاقتك الخاصة، وتأكد من ظهورها في Stripe وفي أودو، ثم استردّ قيمتها. بهذا تثبت سلامة المسار الفعلي من طرف إلى طرف قبل أن يستخدمه عملاؤك.

الاسترداد والمدفوعات المتكررة

عمليات الاسترداد

يدعم أودو تنفيذ الاسترداد مباشرةً من معاملة الدفع عند تفعيل Stripe، فلا تحتاج إلى التنقل إلى لوحة تحكم Stripe. افتح المعاملة من الفاتورة المرتبطة واستخدم إجراء الاسترداد (Refund)؛ يستدعي أودو خدمة Stripe ويعكس عملية الخصم، ويمكنك بعد ذلك إصدار إشعار دائن مقابل لإبقاء دفاترك وسجلات ضريبة القيمة المضافة متطابقة. وفي حالات الاسترداد الجزئي، تأكد من تطابق مبلغ الإشعار الدائن مع القيمة المستردة حتى تبقى ضريبة المخرجات المُبلَّغ عنها صحيحة.

الاشتراكات والفوترة الدورية

بالنسبة للإيرادات المتكررة، يخزّن تطبيق الاشتراكات في أودو رمز الدفع الخاص بالعميل (Token) بعد أول عملية ناجحة عبر Stripe، ثم يخصم تلقائياً من البطاقة المحفوظة عند كل تجديد. وهنا تحديداً يثبت الويب هوك قيمته: فالتجديدات تتم من خادم إلى خادم دون حضور العميل، لذا يعتمد أودو على استدعاءات Stripe لتأكيد سداد كل فترة ولرصد التجديدات الفاشلة ومتابعة تحصيلها. اختبر عملية تجديد في وضع الاختبار قبل إطلاق أي منتج اشتراك، وتأكد من تفعيل السماح بحفظ البطاقات (Tokenization) في مزوّد Stripe حتى يمكن استخدامها في الدفعات المستقبلية.

أخطاء شائعة نراها في الميدان

• خلط مفاتيح الاختبار بمفاتيح التشغيل الفعلي. اقتران مفتاح pk_live_ بمفتاح sk_test_ يُنتج خطأ مصادقة عند كل عملية دفع. يجب أن يتطابق المفتاحان مع البيئة نفسها، وأن يكون كلاهما فعلياً قبل تفعيل المزوّد.
• غياب الويب هوك أو سر التوقيع. تظهر الدفعات ناجحة في Stripe بينما يبقى الطلب في أودو عرض سعر أو فاتورة غير مدفوعة. هذه هي المشكلة الأولى في تذاكر دعم Stripe — تحقق دائماً من تسليم أحداث الويب هوك.
• عدم تطابق العملة. إذا كانت أسعارك في أودو بالدرهم بينما حساب Stripe مضبوط على عملة عرض أخرى، فسيرى العملاء تحويلات عملة وستتحمل أنت فروق الصرف. أبقِ عملة الشركة وقوائم أسعار المنتجات وتحويلات Stripe كلها على الدرهم الإماراتي.
• احتساب ضريبة القيمة المضافة في الطبقة الخطأ. يخصم Stripe المبلغ الإجمالي الذي يرسله إليه أودو؛ فهو لا يحتسب ضريبة 5% نيابةً عنك. تأكد من ضبط الضريبة على المنتج أو الطلب داخل أودو حتى تكون الفاتورة — لا Stripe — مرجعك المعتمد في تقارير الهيئة الاتحادية للضرائب.
• تجاهل رسوم Stripe عند التسوية البنكية. يخصم Stripe رسوم المعالجة قبل التحويل، فالمبلغ الذي يصل إلى حسابك المصرفي بالدرهم أقل من إجمالي الفاتورة. سجّل الرسوم كمصاريف بنكية أثناء التسوية حتى يطابق رصيدك البنكي في أودو الواقع.

اضبط الإعداد بشكل صحيح من المرة الأولى

يعمل Stripe وأودو معاً بسلاسة، لكن التفاصيل — الويب هوك، والمفاتيح المطابقة لبيئتها، وعملة الدرهم، وضريبة قيمة مضافة تغذي إقرارات نظيفة لدى الهيئة الاتحادية للضرائب — هي الفاصل بين إعداد سريع وأسابيع من معاناة التسويات. أوكلاند هي الشريك الذهبي الأول لأودو في الإمارات وجزء من مجموعة آرمور، وخلفنا أكثر من 120 مشروع تنفيذ لأودو ومدة إطلاق نموذجية لا تتجاوز 90 يوماً. إذا أردت منظومة دفع مهيأة ومختبرة ومسوّاة بشكل صحيح من اليوم الأول، فاحجز تقييماً مجانياً مع فريقنا من المستشارين المعتمدين وسنرسم لك الإعداد الأنسب لنشاطك.