VibeFox Omise for PrestaShop — المساعدة

المتطلبات

PrestaShop: من 8.0 إلى 9.x.

PHP: 8.0 أو أحدث. لا تُثبَّت الوحدة على إصدارات PHP الأقدم.

HTTPS: حقول البطاقة موجودة في صفحة الدفع، لذا يجب أن تُقدَّم صفحة الدفع عبر HTTPS. ومع ذلك لا تصل بيانات البطاقة إلى خادمك أبدًا. ترسل Omise الـ webhooks إلى عناوين HTTPS فقط، ويجب أن تكون صفحة 3-D Secure الخاصة بالبنك عنوان HTTPS.

العملة: إحدى العملات THB وJPY وSGD وMYR وUSD وEUR وGBP وAUD وCAD وCHF وCNY وDKK وHKD. لسلة بأي عملة أخرى تُخفى طريقة الدفع في صفحة الدفع.

حساب Omise: تحتاج إلى المفتاح العام والمفتاح السري لحساب Omise الخاص بك، لوضعي الاختبار والإنتاج، وتجدهما في Settings > Keys في لوحة تحكم Omise، إلى جانب نقطة نهاية webhook في Settings > Webhooks (انظر الإعدادات).

مفتاح ترخيص VibeFox: يُشترى من vibefox.net. يعمل مفتاح واحد على نطاق واحد.

التثبيت

1. في لوحة الإدارة، انتقل إلى Modules > Module Manager وانقر Upload a module. اختر ملف ZIP الخاص بالوحدة.

2. عند انتهاء الرفع، انقر Configure، أو ابحث لاحقًا عن VibeFox Omise Payment في قائمة الوحدات وانقر Configure.

3. أدخل مفتاح ترخيص VibeFox في حقل License key داخل كتلة الترخيص أعلى صفحة Configure، ثم انقر على Activate (انظر مفتاح الترخيص).

4. أدخل مفاتيح Omise للاختبار والإنتاج، وأضف في لوحة تحكم Omise عنوان الـ webhook المعروض في صفحة الإعدادات (انظر الإعدادات).

5. فعّل Enable/Disable وانقر Save. اختبر دفعة في وضع الاختبار ببطاقة اختبار من Omise، مثل 4242 4242 4242 4242، ثم أوقف Test mode.

عند التثبيت تُنشئ الوحدة ثلاث حالات للطلب: Omise payment authorized وOmise payment on hold وAwaiting Omise payment. تُعرض طريقة الدفع للدول النشطة وقت التثبيت. إذا فعّلت دولًا أخرى لاحقًا، فاسمح بالوحدة لها في Payment > Preferences، حيث يمكنك أيضًا تقييدها حسب العملة ومجموعة العملاء.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Omise Payment > Configure. لكل قسم زر Save الخاص به، وهو يحفظ الصفحة كاملة. وفوق الحقول تعرض الصفحة Test mode is on — orders are charged with the test keys, no real money is moved. طالما وضع الاختبار مفعّل، وتحذّر إذا كان المفتاح العام أو السري للوضع الحالي مفقودًا، وتحذّر أيضًا عندما لا تقبل Omise العملة الافتراضية لمتجرك. في هذه الحالات تُخفى طريقة الدفع في صفحة الدفع.

Omise

Enable/Disable: Enable card payments via Omise يفعّل طريقة الدفع أو يعطّلها. الافتراضي: off.

Title: اسم طريقة الدفع الذي يراه العميل في صفحة الدفع، وهو أيضًا الاسم المحفوظ في الطلب. الافتراضي: Credit / Debit Card. مطلوب.

Description: النص المعروض فوق نموذج البطاقة في صفحة الدفع. الافتراضي: Pay securely with your credit or debit card via Omise.

مفاتيح API

تجد مفاتيحك في لوحة تحكم Omise تحت Settings > Keys. تبدأ مفاتيح الاختبار بـ pkey_test_ وskey_test_، وتبدأ مفاتيح الإنتاج بـ pkey_ وskey_. عند الحفظ، لا يُحفظ المفتاح ذو البادئة الخاطئة (مثل مفتاح اختبار في حقل الإنتاج): يبقى القديم كما هو وتظهر رسالة تحذير.

Test mode: يستخدم مفاتيح الاختبار، ولا تُجرى خصومات حقيقية. يبدّل المفتاحين معًا. تستخدم عمليات التحصيل والاستردادات وفحوص الحالة للطلب دائمًا مفاتيح الوضع الذي دُفع فيه الطلب. الافتراضي: on.

Test public key: المفتاح العام لوضع الاختبار، pkey_test_...

Test secret key: المفتاح السري لوضع الاختبار، skey_test_...

Live public key: المفتاح العام لوضع الإنتاج، pkey_...

Live secret key: المفتاح السري لوضع الإنتاج، skey_...

لا تُعرض المفاتيح السرية المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييرها.

Clear saved secrets: ضع علامة على مفتاح سري وانقر Save لحذفه. الحقل الفارغ يُبقي القيمة المحفوظة.

الدفع والـ webhook

Webhook URL: عنوان الـ webhook لمتجرك. مع الروابط الودية يبدو هكذا: https://your-shop/module/wcp_omise_payment/webhook. انسخه تمامًا كما تعرضه الإعدادات، وأضفه في لوحة تحكم Omise تحت Settings > Webhooks (HTTPS فقط). تتعامل الوحدة مع هذه الأحداث (وهي مدرجة في هذا القسم أيضًا):

لا توقّع Omise على الـ webhooks، لذلك لا يُوثق بمحتوى الـ webhook أبدًا: يجب أن يكون الخصم قد أنشأه هذا المتجر لتلك السلة، وتُعاد قراءة حالته من واجهة Omise البرمجية بالمفتاح السري لوضع الدفع. ومن دون الـ webhook، لا يُنشأ تلقائيًا الطلب الذي يغلق عميله المتصفح أثناء 3-D Secure، ولا تُلتقط عمليات التحصيل التي تتم في لوحة تحكم Omise حتى تنقر Sync payment status.

Payment action: ما يحدث لمبلغ البطاقة.

Per-charge webhook: يرسل عنوان الـ webhook مع كل خصم. مفيد عندما تشترك عدة متاجر في حساب Omise واحد. يعمل فقط إذا كان المتجر يستخدم HTTPS، وإلا يُستخدم الـ webhook المضبوط في اللوحة. الافتراضي: off.

متقدم

Debug log: يكتب طلبات API وأحداث الدفع في logs/omise_p_debug.log.php داخل مجلد الوحدة. لا يمكن قراءة الملف من الويب. لا تُسجَّل المفاتيح ولا الرموز ولا بيانات البطاقة أبدًا. الافتراضي: off. ولا يُكتب شيء طالما هو معطّل، بما في ذلك الأخطاء، لذلك فعّله عندما تبحث عن مشكلة.

Log: يعرض حجم السجل وأحدث إدخالاته، مع زر لمسحه.

Delete data on uninstall: عند تفعيله، يؤدي إلغاء تثبيت الوحدة إلى حذف الإعدادات وسجل التصحيح. أما خصومات Omise والاستردادات الخاصة بالطلبات فهي جزء من سجل المدفوعات وتُحفظ دائمًا. الافتراضي: off.

الدفع

في خطوة الدفع يختار العميل طريقة الدفع (افتراضيًا Credit / Debit Card) ويملأ نموذج البطاقة: Name on card وCard number وExpiry month (MM) وExpiry year (YYYY) وSecurity code (CVV). في وضع الاختبار يعرض النموذج TEST MODE — use Omise test cards (e.g. 4242 4242 4242 4242), no real charges are made. عندما يقدّم العميل الطلب، يحوّل Omise.js البطاقة إلى رمز لمرة واحدة داخل المتصفح، مستخدمًا عنوان الفوترة من السلة. لا تُرسل حقول البطاقة إلى متجرك أبدًا. تظهر الحقول الناقصة أو غير الصالحة أسفل النموذج، مثل Please enter a valid card number.

ثم ينشئ متجرك الخصم بالمفتاح السري لإجمالي السلة بعملة السلة. وصف الخصم هو اسم المتجر ورقم السلة، ويُحفظ معرّف السلة في البيانات الوصفية للخصم. لا يوجد طلب في هذه المرحلة. إذا طلب البنك 3-D Secure، يُوجَّه العميل إلى صفحة البنك ثم يعود إلى متجرك، وتُعاد قراءة النتيجة من واجهة Omise البرمجية.

لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Omise: يجب أن يكون الخصم محصّلًا، وأن يطابق مبلغه وعملته السلة. يرى العميل صفحة تأكيد الطلب المعتادة مع Your card payment has been received. وعند استخدام Authorize only تقول الصفحة Your card payment has been authorized. The amount will be charged when your order is processed. وإذا ما زالت Omise تعرض الدفع كمعلّق، يُنشأ الطلب في Awaiting Omise payment وتعرض الصفحة Your payment is being confirmed by Omise. You will receive an e-mail as soon as it is confirmed — please do not pay again. وإذا تعذّر تأكيد الدفع مباشرة بعد 3-D Secure، تعرض صفحة Payment confirmation الرسالة We could not confirm your payment yet. If your card was charged, the order will be updated automatically — please do not pay again. وزر Check again.

إذا رُفضت البطاقة، لا يُنشأ أي طلب. يبقى العميل في صفحة الدفع مع Payment failed: وسبب، مثل عدم كفاية الرصيد أو رمز أمان غير صالح أو رفض من مُصدِر البطاقة، ويمكنه المحاولة مجددًا بالسلة نفسها. وإذا فشل 3-D Secure، يعود العميل إلى صفحة الدفع مع السبب؛ وإذا انتهت صلاحية الخصم أو أُلغي في الأثناء، تكون الرسالة The payment was not completed. Please try again.

لا تُخصم المحاولة المعادة مرتين أبدًا: إذا كان الخصم السابق للسلة مدفوعًا أو مفوَّضًا بالفعل، يُنشأ الطلب دون خصم جديد. تنتهي صلاحية محاولة 3-D Secure غير المكتملة قبل إجراء أي خصم جديد. وإذا بقي خصم ثانٍ مدفوعًا لسلة لديها طلب بالفعل (مثلًا في تبويب متصفح آخر)، فلا يتغير الطلب، وتطلب منك ملاحظة استرداد الخصم أو إلغاءه في لوحة تحكم Omise.

يعمل الـ webhook أثناء وجود المتجر في وضع الصيانة، ولا يتأثر بقيود الدول في متجرك.

تقبل الوحدة البطاقات فقط. ولا تتضمن طرق الدفع الأخرى في Omise (PromptPay وTrueMoney والخدمات المصرفية عبر الهاتف والتقسيط)، ولا البطاقات المحفوظة أو عملاء Omise، ولا الاشتراكات، ولا التحصيل الجزئي.

الطلبات والاستردادات

حالات الطلب

No order yet: العميل في 3-D Secure، أو رُفضت البطاقة. السلة فقط هي الموجودة.

Payment accepted: تم تأكيد الدفع. يُسجَّل الدفع بمعرّف خصم Omise (chrg_...) كمعرّف للمعاملة، وتعرض ملاحظة المبلغ والخصم وطريقة التأكيد (صفحة الدفع، أو العودة من 3-D Secure، أو الـ webhook، أو إعادة محاولة الدفع، أو التحصيل اليدوي، أو المزامنة اليدوية). الملاحظات رسائل خاصة بالطلب، ولا تظهر إلا في لوحة الإدارة.

Omise payment authorized: فُوّضت البطاقة مع Authorize only. استخدم Capture payment أو Void authorization.

Awaiting Omise payment: لم تؤكد Omise الدفع بعد. يحدّث الـ webhook أو Sync payment status الطلب.

Omise payment on hold: مبلغ الخصم أو عملته يختلفان عن الطلب، مثلًا إذا تغيّرت السلة أثناء 3-D Secure. تعرض الملاحظة القيمتين. يبقى الدفع المحصَّل مسجلًا في الطلب. راجع الطلب ثم نفّذه أو استرد الدفع.

Payment error: فشل دفع معلّق لاحقًا. لا يُخفَّض الطلب المدفوع أبدًا بسبب حدث فشل لاحق.

Canceled: انتهت صلاحية الخصم أو أُلغي التفويض.

Refunded: استُرد الدفع بالكامل عبر الوحدة.

إذا وصل خصم مدفوع أو مفوَّض لطلب بحالة ملغى أو مسترد بالفعل، فلن يُعاد فتح الطلب. تطلب منك ملاحظة واحدة مراجعة لوحة تحكم Omise واسترداد الطلب أو إعادة فتحه يدويًا.

كتلة الدفع في Omise

تعرض صفحة الطلب كتلة Omise payment تتضمن معرّف الخصم وإجراء الدفع وحالة الخصم وعلامة البطاقة وآخر أرقامها والمبالغ المخصومة ومبلغ الطلب والمبلغ المسترد، وشارة Test mode للمدفوعات التجريبية، وسجل الاستردادات. تحتاج أزرار الكتلة إلى صلاحية تعديل الطلبات والمفتاح السري للوضع الذي تمت فيه عملية الدفع. لا يلزم الوصول إلى صفحات الوحدات. تُعرض نتيجة كل إجراء في أعلى الكتلة.

Capture payment: يحصّل المبلغ المفوَّض بالكامل ويضع الطلب في Payment accepted. يظهر فقط للطلبات المفوَّضة.

Void authorization: يلغي التفويض؛ لا يُحصَّل أي مبلغ ويُضبط الطلب على Canceled. يظهر فقط للطلبات المفوَّضة.

Sync payment status: يقرأ الخصم من Omise ويحدّث الطلب. تعرض الملاحظة أيضًا الإجمالي المسترد في Omise.

الاستردادات

في كتلة Omise payment أدخل المبلغ (يُملأ المبلغ الذي لم يُسترد بعد تلقائيًا)، واختياريًا السبب، ثم انقر Refund via Omise. أكّد السؤال Refund this amount through Omise? This cannot be undone. الاستردادات الكاملة والجزئية مدعومة. تُجرى الاستردادات بالمبلغ والعملة اللذين حصّلتهما Omise، لذلك بعد عدم تطابق المبلغ أو العملة يمكنك الاسترداد حتى المبلغ الذي دفعه العميل فعليًا، لا إجمالي الطلب. يُرسل الاسترداد في الوضع الذي تمت فيه عملية الدفع، لذلك يجب ضبط المفتاح السري لذلك الوضع. يُحفظ السبب مع الاسترداد لدى Omise. يُضاف الاسترداد الناجح إلى سجل الاستردادات والملاحظات، مع معرّف استرداد Omise. يضبط الاسترداد الكامل الطلب على Refunded؛ أما الاسترداد الجزئي فلا يغيّر الحالة. وبالنسبة إلى تفويض لم يُحصَّل بعد، لا يمكن إلا الاسترداد الكامل، وهو يلغي التفويض. إذا رفضت Omise الاسترداد، تعرض الكتلة Refund failed. مع رسالة Omise، ولا يُسجَّل أي استرداد.

لا تُنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop على صفحة الطلب لا تعيد المال عبر Omise. الاستردادات التي تتم في لوحة تحكم Omise لا تُسجَّل في PrestaShop؛ يعرض Sync payment status الإجمالي المسترد.

مفتاح الترخيص

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Omise Payment هي أول كتلة في صفحة Modules > Module Manager > VibeFox Omise Payment > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مُقنّعًا، والحالة (مثل تاريخ انتهاء الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: presta-payment-omise والرابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. لا يستطيع تغيير المفتاح إلا الموظفون الذين لديهم صلاحية Configure للوحدة. تتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل المفتاح غير موجود أو هذا المفتاح يخص منتجًا آخر أو تم بلوغ حد النطاقات أو انتهت صلاحية الترخيص في مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. إذا تعذّر الوصول إلى خادم التراخيص، تواصل الوحدة العمل بآخر حالة معروفة.

يعمل المفتاح الواحد على نطاق واحد فقط: نطاق المتجر الرئيسي، وكذلك في إعداد المتاجر المتعددة. إزالة المفتاح من المتجر لا تحرر خانة النطاق. حرّر الخانة من حسابك على vibefox.net.

بدون مفتاح نشط لا تُعرض طريقة الدفع Omise للعملاء عند إتمام الشراء. وإذا بُدئ الدفع رغم ذلك، يرى العميل طريقة الدفع هذه غير متاحة. يرجى اختيار طريقة أخرى. ولا تعرف واجهة متجر PrestaShop أنك مسجّل الدخول إلى لوحة الإدارة، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء مفتاح، لكن لا يمكنك اختبارها عند إتمام الشراء. يظهر تذكير في Modules > Module Manager على تبويب Alerts. الطلبات الحالية لا تتأثر: المدفوعات التي بدأت بالفعل ما تزال تُؤكَّد، ويستمر عمل الاستردادات.

عند انتهاء الترخيص تواصل الوحدة العمل، لكن التحديثات والدعم يتطلبان التجديد. تُعاد مراجعة الحالة تلقائيًا أثناء عملك في لوحة الإدارة: مرة يوميًا خلال أول 14 يومًا بعد إدخال المفتاح، ثم مرة أسبوعيًا. لا حاجة إلى مهمة cron. إلغاء تثبيت الوحدة أو إعادة ضبطها يزيل دائمًا مفتاح الترخيص وحالة الترخيص.

استكشاف الأخطاء وإصلاحها

Omise does not appear at checkout: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن المفتاحين للوضع الحالي مُدخلان (مفاتيح الاختبار في وضع الاختبار، ومفاتيح الإنتاج في غير ذلك)، وأن عملة السلة من العملات المدعومة. تعرض صفحة الإعدادات تحذيرًا عند غياب المفاتيح. وفي Payment > Preferences تحقق من السماح بالوحدة لعملة السلة ودولة العميل ومجموعة العميل.

The payment went through, but no order was created or the order stays Awaiting Omise payment: الـ webhook لا يعمل. في لوحة تحكم Omise تحقق من أن عنوان الـ webhook مطابق تمامًا للعنوان المعروض في Webhook URL، وأنه يستخدم HTTPS. في طلب موجود انقر Sync payment status. فعّل Debug log لرؤية ردود الـ webhook.

Webhook answers Charge ID does not match order or Order not found: الخصم في الحدث لم يُنشئه هذا المتجر لتلك السلة. لا يتغير شيء.

Webhook answers Order is being processed, retry later or Failed to verify charge: السلة قُفلت بطلب آخر في اللحظة نفسها، أو تعذّر الوصول إلى واجهة Omise البرمجية، أو المفتاح السري لوضع الدفع مفقود. ستعيد Omise محاولة الـ webhook.

Webhook answers The order could not be created, retry later: تعذّر إنشاء الطلب، مثلًا لأن الوحدة معطّلة. فعّل Debug log لرؤية السبب.

The webhook URL shows Method not allowed in the browser: هذا طبيعي. يقبل العنوان الطلبات الصادرة من Omise فقط.

Warning on save: key must start with ... or must be a live key: لُصق مفتاح في الحقل الخطأ ولم يُحفظ. تبدأ مفاتيح الاختبار بـ pkey_test_ / skey_test_، وتبدأ مفاتيح الإنتاج بـ pkey_ / skey_.

The customer sees Card payments are temporarily unavailable: المفاتيح غير صحيحة، أو رمز البطاقة يخص الوضع الآخر (رمز اختبار في الإنتاج أو العكس). تحقق من المفاتيح وTest mode.

The customer sees We could not reach the payment provider: لم يصل رد صالح من Omise أثناء إنشاء الخصم. قد يكون الخصم قد أُنشئ؛ تحقق من لوحة تحكم Omise قبل أن يدفع العميل مرة أخرى.

The customer sees This order is already being paid: أُرسلت صفحة الدفع مرتين في اللحظة نفسها. ينتظر العميل قليلًا ويتحقق من بريده الإلكتروني قبل المحاولة مجددًا.

Order is Omise payment on hold after payment: اقرأ الملاحظة في الطلب (انظر حالات الطلب)، ثم نفّذ الطلب أو استرد الدفع.

Refund fails with a message about the mode: تمت عملية الدفع في وضع الاختبار أو الإنتاج، والمفتاح السري لذلك الوضع غير مضبوط. أدخله وأعد المحاولة.

Partial refund of an authorized order fails: الدفع مفوَّض فقط. حصّله أولًا، أو استرد المبلغ كاملًا لإلغائه.

إلغاء التثبيت

انتقل إلى Modules > Module Manager، وافتح القائمة بجوار VibeFox Omise Payment، واختر Uninstall. مفتاح الترخيص وحالة الترخيص لهذه الوحدة يُحذفان دائمًا. إذا كان Delete data on uninstall مفعّلًا، تُحذف الإعدادات وسجل التصحيح. وإذا كان معطّلًا، تُحفظ جميع الإعدادات لإعادة التثبيت لاحقًا. تُحفظ دائمًا خصومات Omise واستردادها وحالات الطلب Omise payment authorized وOmise payment on hold وAwaiting Omise payment، حتى يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت. تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

Omise علامة تجارية مملوكة لصاحبها. هذه الوحدة غير مرتبطة بـ Omise ولا تحظى بتأييدها.