إضافات أنظمة إدارة المحتوى والتجارة الإلكترونية

تتيح إضافاتنا قبول مدفوعات Orange Money سيراليون دون كتابة أي شيفرة. وتعمل جميعها بالطريقة نفسها:

1. يُنشأ الطلب ويُحوَّل العميل إلى صفحة الدفع في SOAMTAR (قيمة payment_url التي يعيدها POST https://app.so-amtar.com/v1/payments).
2. يوافق العميل على الدفع من هاتفه بإدخال رمز PIN الخاص بـ Orange Money.
3. ترسل SOAMTAR إشعار webhook موقّعًا إلى متجرك، ولا يُعلَّم الطلب مدفوعًا إلا إذا تطابق المبلغ والعملة.

المنصة	الحزمة / المجلد	الإصدار	المتطلبات	العملات
WooCommerce	soamtar-woocommerce-gateway	1.1.0	WordPress 5.8+، WooCommerce 6.0+، PHP 7.4+	SLE، USD، EUR
Magento 2	soamtar/magento2-payment (Soamtar_Payment)	1.1.0	Magento 2.4.4+، PHP 8.1+	SLE، USD، EUR
PrestaShop	soamtar	1.1.0	PrestaShop 1.7.7+ / 8، PHP 7.4+	SLE، USD، EUR
Drupal Commerce	soamtar_commerce	1.1.0	Drupal 9.3+ / 10 / 11، Commerce 2.x، PHP 8.1+	SLE، USD، EUR
Odoo	payment_soamtar	17.0.1.1.0	Odoo 17.0، Python 3.10+	SLE فقط

غير متوفرة بعد في المتاجر الرسمية

لم تُنشر الإضافات بعد في متاجر WordPress أو Magento أو PrestaShop أو Drupal أو Odoo. ثبّتها من المستودع (git clone أو ملف zip) كما هو موضح أدناه.

الإعداد المشترك

تحتاج كل إضافة إلى ثلاث قيم من لوحة تحكم SOAMTAR:

القيمة	المصدر
المفتاح السري للاختبار sk_test_…	مفاتيح API. تُحاكى المدفوعات على المضيف نفسه (https://app.so-amtar.com/v1) دون أي حركة لأموال حقيقية.
المفتاح السري الحقيقي sk_live_…	مفاتيح API، بعد تفعيل حسابك للإنتاج.
سرّ الـ Webhook	سرّ التوقيع لنقطة نهاية webhook مسجّلة في لوحة التحكم (Developers → Webhooks). مطلوب دائمًا، حتى مع callback_url.

لكل إضافة مفتاح Test mode يختار بين مفتاح الاختبار والمفتاح الحقيقي. تبقى المفاتيح السرية على خادمك فقط، فلا تضعها أبدًا في قالب أو ملف JavaScript.

عنوان الـ Webhook: تلقائي في المتاجر العاملة بـ HTTPS. ترسل كل إضافة عنوان الـ webhook الخاص بها في الحقل callback_url مع كل دفعة. عندها تُسلّم SOAMTAR الأحداث الموقّعة لتلك الدفعة (ولعمليات استردادها) إلى المتجر، بنفس الحمولة والتوقيع وإعادة المحاولة كما في نقطة نهاية مسجّلة. توقّع SOAMTAR هذه الإرسالات بسرّ أقدم نقطة نهاية webhook نشطة لديك في البيئة نفسها، لذا تحتاج إلى نقطة نهاية واحدة على الأقل في لوحة التحكم وإلى سرّ توقيعها في الإضافة.

يجب أن يكون callback_url عنوان HTTPS عامًا. إذا لم يكن المتجر يعمل بـ HTTPS، تحذفه الإضافة وتطلب منك (إشعار إداري أو سجل أو صفحة الإعدادات) تسجيل عنوان المتجر المذكور أدناه كنقطة نهاية webhook في لوحة التحكم، مشتركة في payment.success وpayment.failed وpayment.cancelled وpayment.expired وrefund.success وrefund.failed وpayment.refunded وpayment.partially_refunded (Odoo: كل أحداث payment.* وrefund.*). احتفظ بإصدار الحمولة الافتراضي (legacy).

يُجاب على زر Send test event في لوحة التحكم (webhook.test) بـ 200 من كل الإضافات دون تعديل أي طلب.

تتحقق جميع الإضافات من الترويسة X-Soamtar-Signature (t=<unix>,v1=<hex>، مع v2= أثناء تدوير السرّ): ‏HMAC-SHA256 للنص "<t>.<الجسم الخام>" بسرّ الـ webhook، مع هامش زمني 300 ثانية. راجع Webhooks.

الاسترداد

تدعم كل الإضافات الاسترداد مباشرة من لوحة إدارة المتجر. تستدعي POST https://app.so-amtar.com/v1/refunds بمعرّف معاملة SOAMTAR والمبلغ (كاملًا أو جزئيًا). تعيد SOAMTAR المال إلى رقم Orange Money الخاص بالدافع وتخصمه من رصيدك في SOAMTAR. الاسترداد غير متزامن: تصل النتيجة النهائية عبر refund.success أو refund.failed (إضافة إلى payment.refunded / payment.partially_refunded). يحتاج مفتاح API إلى الصلاحية can_refund، ويجب أن يغطي رصيدك المبلغ.

المنصة	طريقة الاسترداد
WooCommerce	Refund via SOAMTAR على الطلب
Magento 2	إشعار دائن عبر الإنترنت (Refund وليس "Refund Offline") من الفاتورة
PrestaShop	قسيمة دائنة (استرداد عادي أو جزئي أو إرجاع منتج)، عند تفعيل Refund through Orange Money (SOAMTAR_AUTO_REFUND، مفعّل افتراضيًا)
Drupal Commerce	Refund على الدفعة (البوابة تطبّق SupportsRefundsInterface)
Odoo	زر Refund على الدفعة (كامل أو جزئي)

راجع Refunds للاطلاع على الواجهة البرمجية.

WordPress / WooCommerce

يدعم صفحة الدفع الكلاسيكية وكتل السلة/الدفع، ومتوافق مع HPOS.

التثبيت

cd wp-content/plugins
git clone <عنوان المستودع> soamtar-woocommerce-gateway

أو ارفع ملف zip للمجلد من الإضافات ← أضف جديد ← رفع إضافة، ثم فعّل SOAMTAR for WooCommerce. اضبط عملة المتجر على SLE أو USD أو EUR.

الإعدادات

WooCommerce ← الإعدادات ← المدفوعات ← SOAMTAR (التسميات بالإنجليزية في الواجهة):

الإعداد	ملاحظات
Enable/Disable	يُظهر بوابة الدفع في صفحة الدفع.
Title / Description	نص صفحة الدفع (الافتراضي "Orange Money").
Test mode	يستخدم مفتاح الاختبار السري.
Live secret key / Test secret key	sk_live_… / sk_test_…، مشفّرة عند التخزين.
Webhook secret	إلزامي.
Success redirect URL (optional)	الافتراضي: صفحة «تم استلام الطلب» في WooCommerce.
Failure redirect URL (optional)	الافتراضي: صفحة دفع الطلب.
Debug log	WooCommerce ← الحالة ← السجلات، المصدر soamtar-gateway.

تبقى البوابة مخفية (مع تنبيه في لوحة الإدارة) ما دام ينقصها مفتاح أو سرّ الـ webhook أو عملة متجر مدعومة.

عنوان الـ webhook

https://your-store.example/wp-json/soamtar/v1/webhook

يعمل أيضًا العنوان القديم https://your-store.example/?wc-api=wc_soamtar_gateway.

السلوك

• payment.success: لا يكتمل الطلب إلا إذا تطابق amount وcurrency معه، وإلا يوضع قيد الانتظار مع ملاحظة.
• payment.failed وpayment.cancelled وpayment.expired: يُعلَّم الطلب فاشلًا ما لم يكن مدفوعًا بالفعل.
• تستخدم المحاولة الجديدة بعد فشل الدفع merchant_ref بالشكل 1001-2 و1001-3… (لا يمكن استخدام المرجع إلا مرة واحدة).
• يُحوَّل هاتف الفوترة إلى +232XXXXXXXX متى أمكن، وإلا يُدخل العميل الرقم في صفحة الدفع.
• نقطة الـ webhook محمية بحدّ للطلبات لكل IP، وحدّ أقصى للحجم 1 ميغابايت، وإزالة التكرار، وسجل تدقيق، وقائمة IP مسموح بها اختيارية (المرشِّح soamtar_webhook_ip_allowlist).

Magento 2

التثبيت

انسخ الوحدة إلى app/code/Soamtar/Payment/، أو صرّح بالمستودع كمستودع Composer من نوع VCS/path ثم نفّذ composer require soamtar/magento2-payment. بعد ذلك:

php bin/magento module:enable Soamtar_Payment
php bin/magento setup:upgrade
php bin/magento setup:di:compile
php bin/magento cache:flush

الإعدادات

Stores ← Configuration ← Sales ← Payment Methods ← SOAMTAR — Orange Money (Sierra Leone)

الحقل	مسار الإعداد
Enabled	payment/soamtar/active
Title (الافتراضي "Orange Money")	payment/soamtar/title
Test mode	payment/soamtar/testmode
Test secret key (sk_test_…)	payment/soamtar/test_secret_key (مشفّر)
Live secret key (sk_live_…)	payment/soamtar/live_secret_key (مشفّر)
Webhook secret	payment/soamtar/webhook_secret (مشفّر)
Payment from applicable countries / specific countries	payment/soamtar/allowspecific، payment/soamtar/specificcountry
Debug log	payment/soamtar/debug
Sort order	payment/soamtar/sort_order

لا تُعرض طريقة الدفع إلا إذا كانت عملة الطلب SLE أو USD أو EUR.

عنوان الـ webhook

https://your-store.example/soamtar/webhook/notify

السلوك

• يُنشأ الطلب بحالة pending_payment، ثم ينشئ /soamtar/payment/redirect دفعة SOAMTAR (Idempotency-Key: mage_<increment id>_<protect code>) ويحوّل إلى payment_url. إذا فشل استدعاء API يُلغى الطلب وتُستعاد السلة.
• payment.success بالمبلغ والعملة الصحيحين يسجّل التحصيل (الفاتورة) وينقل الطلب إلى processing؛ وعند عدم التطابق يوضع الطلب قيد الانتظار مع تعليق.
• payment.failed وpayment.cancelled وpayment.expired: يُلغى الطلب الذي في حالة pending_payment.
• يكتفي /soamtar/payment/cancel (عنوان الفشل) باستعادة السلة. للاسترداد، أنشئ إشعارًا دائنًا عبر الإنترنت (Refund): تستدعي الوحدة POST/v1/refunds.

PrestaShop

التثبيت

cd modules
git clone <عنوان المستودع> soamtar

يجب أن يكون اسم المجلد soamtar. يمكنك أيضًا ضغطه بالشكل soamtar/… ورفعه من الوحدات ← مدير الوحدات ← رفع وحدة، ثم تثبيت SOAMTAR — Orange Money.

الإعدادات

الوحدات ← SOAMTAR — Orange Money ← تهيئة

الحقل	مفتاح الإعداد	ملاحظات
Test mode	SOAMTAR_TEST_MODE	مفعّل افتراضيًا.
Test secret key	SOAMTAR_TEST_SECRET_KEY	sk_test_…
Live secret key	SOAMTAR_LIVE_SECRET_KEY	sk_live_…
Webhook secret	SOAMTAR_WEBHOOK_SECRET

ترك حقل كلمة المرور فارغًا يحتفظ بالقيمة المحفوظة. فعّل الوحدة أيضًا لعملات SLE أو USD أو EUR من الدفع ← التفضيلات: لا يظهر خيار الدفع إلا إذا كان المفتاح النشط وسرّ الـ webhook مضبوطين وكانت عملة السلة مدعومة.

عنوان الـ webhook

https://your-shop.example/module/soamtar/webhook

يُعرض العنوان الدقيق (حسب إعدادات الروابط الودّية) في صفحة التهيئة.

السلوك

• يُنشأ الطلب بحالة «Awaiting Orange Money payment»؛ وإذا فشل استدعاء API ينتقل إلى «خطأ في الدفع» وتُستعاد السلة.
• لا تُعدَّل إلا الطلبات التي ما زالت بانتظار الدفع: payment.success بالمبلغ والعملة الصحيحين ← «تم قبول الدفع»؛ payment.failed ← «خطأ في الدفع»؛ payment.cancelled / payment.expired ← «ملغى». إذا اختلف المبلغ أو العملة يبقى الطلب معلّقًا ويُسجَّل خطأ.
• يعرض module/soamtar/return صفحة التأكيد أو يستعيد السلة، ولا يغيّر حالة الطلب أبدًا.

Drupal Commerce

بوابة دفع خارج الموقع (offsite). يُسجَّل الدفع عند عودة العميل (بالاستعلام عن الحالة) أو عبر الـ webhook، أيهما يصل أولًا.

التثبيت

انسخ الوحدة إلى modules/custom/soamtar_commerce (أو صرّح بالمستودع كمستودع Composer من نوع VCS/path ثم نفّذ composer require soamtar/drupal-commerce)، ثم:

drush en soamtar_commerce -y
drush cr

الإعدادات

Commerce ← الإعدادات ← بوابات الدفع ← إضافة بوابة دفع، الإضافة SOAMTAR (Orange Money Sierra Leone).

الإعداد	ملاحظات
Mode	‏Test يستخدم مفتاح الاختبار، وLive المفتاح الحقيقي.
Test secret key (sk_test_…)	اتركه فارغًا للاحتفاظ بالقيمة المحفوظة.
Live secret key (sk_live_…)	اتركه فارغًا للاحتفاظ بالقيمة المحفوظة.
Webhook secret	يظهر عنوان الـ webhook أسفل هذا الحقل بعد حفظ البوابة.

عنوان الـ webhook

https://your-site.example/payment/notify/<الاسم الآلي للبوابة>

السلوك

• قيمة merchant_ref هي <معرّف الطلب>-<رقم المحاولة>. يُرسل رقم +232 إذا كان لملف الفوترة حقل field_phone.
• عند العودة، تستعلم الوحدة GET /v1/status/{معرّف المعاملة}: ‏success يسجّل الدفع؛ وfailed أو cancelled أو expired يعيد العميل إلى صفحة الدفع؛ والدفع المعلّق يسمح بإكمال الطلب بانتظار الـ webhook.
• يسجّل payment.success دفعة مكتملة مرة واحدة لكل معاملة SOAMTAR، وفقط إذا تطابق amount وcurrency مع رصيد الطلب.

Odoo

مزوّد دفع للتجارة الإلكترونية في Odoo والفواتير وروابط الدفع.

التثبيت

1. انسخ payment_soamtar/ إلى مسار الإضافات (addons) في Odoo.
2. أعد تشغيل Odoo، وحدّث قائمة التطبيقات، وابحث عن SOAMTAR Payment Provider وثبّته.
3. فعّل عملة SLE (المحاسبة ← الإعدادات ← العملات). لا يُعرض المزوّد إلا للطلبات بعملة SLE.

الإعدادات

الفوترة / الموقع ← الإعدادات ← مزوّدو الدفع ← SOAMTAR (Orange Money)

الحقل	القيمة
الحالة	وضع الاختبار (يستخدم sk_test_…) أو مفعّل (يستخدم sk_live_…)
Test Secret Key / Live Secret Key	من لوحة تحكم SOAMTAR
Webhook Secret	سرّ التوقيع لنقطة النهاية أدناه

عنوان الـ webhook

https://your-odoo.example/payment/soamtar/webhook

السلوك

• قيمة merchant_ref هي مرجع معاملة Odoo، ويعود العميل إلى /payment/soamtar/return.
• عند العودة وعند استلام الـ webhook، يقرأ Odoo حالة الدفع من واجهة SOAMTAR API (ولا يثق أبدًا بعنوان المتصفح أو بجسم الـ webhook)، ويتحقق من المبلغ والعملة، ثم يؤكد المعاملة أو يلغيها أو يعلّمها فاشلة.
• يردّ الـ webhook بـ 400 إذا لم يتطابق السرّ (أو إذا انحرفت ساعة الخادم بأكثر من 5 دقائق)، وبـ 503 إذا لم يُضبط Webhook Secret.