VibeFox Midtrans for OpenCart — المساعدة

المتطلبات

OpenCart: ‏3.0.x (تم الاختبار على 3.0.5.0) أو الإصدار 4.0.2 والإصدارات الأحدث (تم الاختبار على 4.1.0.3).

PHP: ‏8.0 أو أحدث.

العملة: الروبية الإندونيسية (IDR). تقوم Midtrans بالتحصيل بالروبية الإندونيسية فقط، لذلك لا تُعرض طريقة الدفع إلا عندما تكون عملة الدفع هي IDR. لا يوجد تحويل للعملات. أضف العملة IDR في System > Localisation > Currencies إذا لم تكن موجودة في متجرك.

حساب Midtrans: تحتاج إلى Server Key من Midtrans Dashboard > Settings > Access Keys، سواء في لوحة الاختبار (sandbox) أو لوحة الإنتاج. يُستخدم Server Key فقط. ولا يلزم Client Key لـ Snap Redirect. أما طرق الدفع نفسها (GoPay وQRIS والحسابات الافتراضية وغيرها) فتُفعَّل في حساب Midtrans الخاص بك.

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

التثبيت

يحتوي هذا التنزيل على ملف zip واحد فيه حزم الإصدارين من OpenCart. فُكّه على حاسوبك. يحتوي على README.txt، وحزمة OpenCart 3 wcp_midtrans_payment_gateway-oc3-(version).ocmod.zip، وحزمة OpenCart 4 wcp_midtrans_payment_gateway.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.

OpenCart 3

1. في لوحة الإدارة انتقل إلى Extensions > Installer، واضغط Upload، واختر الملف wcp_midtrans_payment_gateway-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا تحتاج Extensions > Modifications إلى تحديث. وبدلًا من أداة التثبيت يمكنك نسخ محتويات المجلد upload الموجود في هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Midtrans Payment Gateway واضغط Install (زر + الأخضر). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.

3. اضغط Edit (زر القلم) لفتح صفحة الإعدادات. الصق مفتاح ترخيص VibeFox الخاص بك في License key ضمن كتلة الترخيص في أعلى الصفحة، ثم اضغط Activate (راجع مفتاح الترخيص).

4. أدخل Server Keys، وانسخ عنوان URL لإشعار الدفع إلى لوحة Midtrans (راجع الإعداد).

5. فعّل Enable/Disable واضغط Save. اختبر في Sandbox، ثم غيّر Environment إلى Production.

OpenCart 4

1. في لوحة الإدارة انتقل إلى Extensions > Installer، واضغط Upload، واختر الملف wcp_midtrans_payment_gateway.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الامتداد من اسم الملف، ولا تعمل الحزمة إذا أُعيد تسميتها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. اضغط Install (زر + الأخضر) بجانبها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Midtrans Payment Gateway، واضغط Install (زر + الأخضر)، ثم Edit (زر القلم).

4. أدخل مفتاح الترخيص وServer Keys وعنوان URL لإشعار الدفع كما في الخطوات من 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. الفرق الوحيد هو عنوان URL لإشعار الدفع (راجع الإعداد).

تبدأ التثبيتات الجديدة بطريقة الدفع معطلة وبيئة Sandbox محددة.

الإعداد

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Midtrans Payment Gateway > Edit. تظهر الأقسام في الجهة اليسرى، ويحفظ الزر Save أسفل القائمة الصفحة كاملة. وفوق الإعدادات تحذرك الصفحة عندما يكون Server Key للبيئة المحددة مفقودًا (وفي هذه الحالة تُخفى طريقة الدفع عند الدفع)، وعندما لا تكون عملة المتجر الافتراضية هي IDR، وتعرض Sandbox mode: payments are simulated, no real money is charged. طالما كانت Sandbox محددة. وبدون صلاحية تعديل الإضافة تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، يجب أن يكون Title بين 1 و128 حرفًا، ويجب أن يكون Sort Order عددًا صحيحًا، ويجب أن يكون Total رقمًا أكبر من أو يساوي 0، ويجب أن يكون Payment page expiry (minutes) عددًا صحيحًا. وإذا كانت قيمة خاطئة، تعرض الصفحة الخطأ ولا يُحفظ شيء.

Midtrans

Enable/Disable: Enable Midtrans payments يفعّل طريقة الدفع أو يعطّلها. الافتراضي: معطّل.

Title: عنوان طريقة الدفع الذي يراه العميل عند الدفع. وهو أيضًا اسم طريقة الدفع المحفوظ في الطلب. الافتراضي: Midtrans. مطلوب.

Description: النص الذي يراه العميل في خطوة Confirm Order فوق زر التأكيد. الافتراضي: Pay securely via Midtrans — GoPay, QRIS, ShopeePay, cards, bank transfer and more. وفي Sandbox يظهر فوقه السطر SANDBOX MODE: no real money is charged.

Sort Order: ترتيب Midtrans بين طرق الدفع عند الدفع. اتركه فارغًا أو أدخل عددًا صحيحًا.

Geo Zone: اعرض Midtrans فقط لعناوين الدفع في المنطقة الجغرافية المحددة. الافتراضي: All zones. تُعدّ المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي الدفع، بعملة المتجر الافتراضية، الذي يجب أن يبلغه الطلب قبل عرض Midtrans. اتركه فارغًا لعرض Midtrans مهما كان المبلغ.

بيانات اعتماد API

انسخ Server Key من Midtrans Dashboard > Settings > Access Keys. يحتوي القسم على روابط إلى لوحة الإنتاج ولوحة الاختبار (sandbox).

Environment: البيئة المستخدمة من Midtrans للمدفوعات الجديدة. عند التبديل تُستخدم المفاتيح وواجهة API للبيئة المحددة. تحتفظ الطلبات بالبيئة التي دُفعت فيها، من أجل الاسترداد والإشعارات. الافتراضي: Sandbox.

Production Server Key: يبدأ بـ Mid-server-. احتفظ به سرًا.

Sandbox Server Key: يبدأ بـ SB-Mid-server-.

لا تُعرض المفاتيح المحفوظة مرة أخرى. يبقى الحقل فارغًا ويعرض Saved — leave empty to keep it. اكتب قيمة جديدة فقط إذا أردت تغييرها. لإزالة مفتاح محفوظ، ضع علامة على Clear the saved key on save أسفل الحقل واضغط Save.

عنوان URL لإشعار الدفع

يخبر الإشعار متجرك بأن دفعة قد تمت. يعرض الحقل Notification URL العنوان الذي يجب استخدامه. في OpenCart 3 وهو بالشكل التالي: https://your-store/index.php?route=extension/payment/wcp_midtrans_payment_gateway/webhook، وفي OpenCart 4 بالشكل التالي: https://your-store/index.php?route=extension/wcp_midtrans_payment_gateway/payment/wcp_midtrans_payment_gateway.webhook، ويُبنى من عنوان واجهة المتجر لتثبيت OpenCart الخاص بك. انسخ العنوان تمامًا كما تعرضه الإعدادات، والصقه في Midtrans Dashboard > Settings > Payment > Notification URL، سواء في لوحة الاختبار (sandbox) أو لوحة الإنتاج التي تستخدمها. يجب أن يكون العنوان قابلًا للوصول من الإنترنت. إذا فتحته في متصفح، فسيعرض شرحًا موجزًا، حتى تتمكن من التحقق من أنه قابل للوصول. كما يستجيب زر Test notification URL في لوحة Midtrans.

يجب أن يحمل كل إشعار توقيعًا صالحًا أنشئ باستخدام أحد Server Keys الخاصة بك، ويجب أن تطابق بيئة المفتاح بيئة الدفعة. تُرفض الإشعارات التي لا تحمل توقيعًا صالحًا. ثم تُعاد قراءة الحالة من واجهة API لحالة Midtrans قبل تغيير الطلب. تتعامل الإضافة مع حالات المعاملات التالية من Midtrans:

من دون عنوان URL للإشعار، لا يُؤكَّد الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع، ولا تُرى الدفعة المؤجلة التي تتم لاحقًا قبل عودة العميل.

إعدادات الدفع

تقوم Midtrans بالتحصيل بالروبية الإندونيسية فقط، وتُرسل المبالغ بالروبية الكاملة. إذا لم تتطابق بنود الطلب مع الإجمالي المقرّب، تُرسل إلى Midtrans سطر Rounding adjustment.

Payment page expiry (minutes): المدة التي يمكن للعميل خلالها الدفع (صفحة Snap، والحساب الافتراضي، وغير ذلك). اتركه فارغًا أو اجعله 0 لاستخدام القيمة الافتراضية من Midtrans.

Order ID prefix: يُضاف إلى الرقم المُرسل إلى Midtrans، حتى تتمكن عدة متاجر من مشاركة حساب Midtrans واحد. والرقم هو معرّف طلب OpenCart مع طابع زمني، مثل OC-123-1700000000. تُقبل الأحرف والأرقام و- _ . ~ فقط، حتى 20 حرفًا؛ وتُحذف الأحرف الأخرى عند الحفظ. وتُتجاهل إشعارات المتاجر الأخرى. الافتراضي: OC-.

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order دون حالة (طلب ناقص). ولا يحصل الطلب على حالة إلا بعد أن تؤكد Midtrans المعاملة. يعرض كل حقل أدناه حالات الطلبات الخاصة بـ OpenCart.

Status after payment: الحالة بعد دفعة مؤكدة. الافتراضي: قيد التنفيذ. اختر حالة مكتملة لتعليم الطلبات المدفوعة كمكتملة، أو حالة مراجعة خاصة بك لمراجعة كل طلب مدفوع يدويًا.

Awaiting Midtrans payment status: تبلغ Midtrans بحالة pending: صدر حساب افتراضي أو رمز متجر مريح أو QRIS، أو لم يكتمل التحقق 3-D Secure للبطاقة. الافتراضي: قيد الانتظار.

Midtrans payment on hold status: تحتاج الدفعة إلى مراجعتك (راجع حالات الطلب). الافتراضي: قيد الانتظار، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Payment failed status: تبلغ Midtrans بالحالة deny أو failure لطلب منتظر. الافتراضي: فشل.

Payment expired / cancelled status: انتهت صلاحية المعاملة المعلّقة لطلب منتظر أو أُلغيت. عندما تضبط بنفسك طلب Midtrans غير المدفوع على هذه الحالة، تُنهى معاملته المعلّقة في Midtrans (مثل حساب افتراضي صادر) حتى لا يمكن دفعها بعد الآن. الافتراضي: ملغي.

Refunded status: استُردت الدفعة بالكامل من صفحة الطلب أو من لوحة Midtrans. الافتراضي: مُسترد.

متقدم

Debug log: يكتب استدعاءات API والإشعارات في midtrans_p_debug.log.php داخل مجلد السجلات في OpenCart (storage/logs). لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء دائمًا. لا تُسجَّل المفاتيح وبيانات العملاء أبدًا. الافتراضي: معطّل.

Log: يعرض حجم السجل وأحدث إدخالاته. اضغط Clear log لإفراغه.

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات البوابة والسجل. تبقى مراجع الدفع في Midtrans وعمليات استرداد الطلبات محفوظة دائمًا، لذلك يمكن استرداد الطلبات القديمة بعد إعادة التثبيت. الافتراضي: معطّل.

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا يتم تصدير Server Keys.

Import: الصق ملف JSON المُصدَّر سابقًا واضغط Import لاستعادة الإعدادات. تبقى Server Keys المحفوظة كما هي.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضيًا Midtrans). وفي خطوة Confirm Order يرى العميل وصفك وملاحظة You will be redirected to the Midtrans payment page (GoPay, QRIS, ShopeePay, cards, bank transfer and more). ينشئ OpenCart الطلب في هذه الخطوة، ولا يزال بلا حالة. عندما يضغط العميل Confirm Order، تُنشئ الإضافة معاملة Midtrans Snap بإجمالي الطلب بالروبية الكاملة، مع بنود الطلب والشحن والخصومات والضرائب وبيانات الفوترة والشحن للعميل، وترسل العميل إلى صفحة الدفع الخاصة بـ Midtrans. وهناك يختار العميل أي طريقة مفعّلة في حساب Midtrans الخاص بك. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، داخل النافذة Payment method options، وينقر على Confirm Order أسفل صفحة الدفع.

بعد الدفع يعود العميل إلى متجرك. ورابط العودة نفسه لا يعلّم الطلب كمدفوع أبدًا: لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Midtrans، سواء عبر الإشعار الموقّع أو عبر طلب إلى واجهة حالة Midtrans عندما يعود العميل. ثم يحصل الطلب على حالته بالطريقة القياسية في OpenCart، مع رسائل البريد المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart. وفي حالة الدفع المؤجل، تعرض الصفحة أيضًا We are waiting for Midtrans to confirm your payment. If you chose a bank transfer, virtual account or convenience store, please complete the payment using the instructions from Midtrans. You will receive an e-mail once the payment is confirmed. وإذا تعذّر الوصول إلى Midtrans عند عودة العميل، تعرض صفحة Payment confirmation النص We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again. مع زر Check again وزر Back to checkout.

إذا غادر العميل صفحة Snap دون أن يدفع، فسيعود إلى الدفع مع الرسالة The Midtrans payment was not completed. You can try again below. وإذا رُفضت الدفعة أو انتهت صلاحيتها، فالرسالة هي Your Midtrans payment was declined or has expired. Please try again or choose another payment method. وتبقى السلة محفوظة. في OpenCart 4 تظهر هذه الرسائل أعلى صفحة الدفع. ينشئ OpenCart 3 طلبًا جديدًا كلما عُرضت خطوة Confirm Order، أما OpenCart 4 فيُبقي طلب الدفع نفسه ويدفعه من جديد، لذلك تعامل الإضافة كل طلبات السلة الواحدة كدفعة واحدة: عندما يدفع العميل مرة أخرى يُعاد استخدام Snap غير مستخدم أو معلّق بالمبلغ نفسه (ويبقى الحساب الافتراضي الصادر صالحًا)؛ وإذا تغيّر المبلغ تُنهى أولًا المعاملة المعلّقة في Midtrans؛ وإذا دُفع Snap سابق في الأثناء، تُؤكَّد تلك الدفعة ويذهب العميل إلى صفحة النجاح دون معاملة جديدة.

في OpenCart 4 يبقى الطلب في صفحة الدفع إلى أن تظهر صفحة النجاح. وإذا أُغلق هذا الطلب دون دفع في الأثناء (مثلًا إذا انتهت الدفعة أو رُفضت أو ألغيته)، يُعاد العميل إلى صفحة الدفع مع الرسالة Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order. ويُنشئ Confirm Order التالي طلبًا جديدًا. وإذا كان الطلب قد تم تقديمه بالفعل وتغيّرت السلة منذ ذلك، فالرسالة هي Your previous order #(number) has already been placed. Your cart has changed: please confirm the new order to pay for it. ويُحسب تغيير السلة، بما فيه الكمية الجديدة، سلة جديدة تحتاج إلى دفعها الخاص. وإذا رُفضت دفعة الطلب أو انتهت بعد إفراغ السلة (مثلًا بعد دفع عبر حساب افتراضي)، يرى العميل The Midtrans payment of order #(number) was declined or has expired, so the order will not be shipped. To buy these items, please place a new order.

إذا تعذّر على Midtrans بدء الدفع، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة فوق الزر: Could not connect to Midtrans. Please try again in a moment.، أو Midtrans payments are temporarily unavailable. Please choose another payment method or contact us. (مثلًا عند وجود Server Key خاطئ)، أو السبب الذي تُعيده Midtrans. ويُكتب السبب التقني في السجل.

يعمل الإشعار أيضًا عندما يكون المتجر في وضع الصيانة، : يسمح OpenCart 3 بمرور طلبات إضافات الدفع، وتضيف الإضافة في OpenCart 4 startup action يسمح بمرور الإشعار وعودة العميل من Midtrans.

تستخدم الإضافة Snap Redirect فقط. ليس فيها نافذة Snap منبثقة، ولا نموذج بطاقة على موقعك، ولا بطاقات محفوظة أو دفع بنقرة واحدة، ولا إعدادات أقساط أو عروض ترويجية (تُضبط طرق الدفع في لوحة Midtrans)، ولا اشتراكات. تُحصَّل مدفوعات البطاقات فورًا، دون تفويض وتحصيل منفصلين.

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

حالات الطلب

No status (missing order): أُرسل العميل إلى Midtrans ولم يدفع، أو لم تؤكد Midtrans الدفعة بعد. في Sales > Orders لا تظهر هذه الطلبات إلا مع الفلتر Order Status مضبوطًا على Missing Orders.

Awaiting Midtrans payment status (الافتراضي قيد الانتظار): اختار العميل طريقة دفع مؤجلة أو بدأ دفعة ببطاقة لم تكتمل. وعندما تُبلغ Midtrans بالدفعة، ينتقل الطلب إلى Status after payment.

Status after payment (الافتراضي قيد التنفيذ): تم تأكيد الدفعة. تعرض ملاحظة طريقة الدفع ومعرّف طلب Midtrans والمعاملة.

Midtrans payment on hold status (الافتراضي قيد الانتظار): دفعة ببطاقة قيد مراجعة الاحتيال (challenge، ولم يُسجَّل مبلغ بعد)، أو لم يتطابق المبلغ المدفوع أو العملة مع الطلب (لا يُعلَّم الطلب كمدفوع)، أو وصلت دفعة لطلب ملغى (لا يُعاد فتح الطلب تلقائيًا). توضح الملاحظة ذلك. تحقّق من الطلب، ثم أكمله أو استرد الدفعة.

Payment expired / cancelled status (الافتراضي ملغي): انتهت صلاحية المعاملة غير المدفوعة لطلب منتظر أو أُلغيت.

Payment failed status (الافتراضي فشل): فشلت الدفعة، أو رُفضت دفعة ببطاقة خضعت للمراجعة.

Refunded status (الافتراضي مُسترد): استُردت الدفعة بالكامل.

يُبلغ OpenCart العميل بتغييرات الحالة هذه بالطريقة المعتادة. وإذا وصلت دفعة ثانية للسلة نفسها، فلا يتغير الطلب. وتطلب منك ملاحظة على الطلب المدفوع استرداد الدفعة الثانية في لوحة Midtrans. وتضيف الدفعة لطلب مُسترد ملاحظة فقط.

الملاحظات هي إدخالات في History الخاص بالطلب، ولا يراها العميل.

تبويب VibeFox Midtrans Payment Gateway

في Sales > Orders افتح طلبًا دُفع عبر Midtrans. في أسفل صفحة الطلب، بجوار History وAdditional، يعرض تبويب VibeFox Midtrans Payment Gateway الحقول: Midtrans order ID، وTransaction ID (مرتبطًا بالمعاملة في لوحة Midtrans لبيئة الدفعة) مع تسمية Sandbox لدفعات الاختبار، وPayment method، وStatus، والمبالغ Paid / refunded، ونموذج الاسترداد، وسجل عمليات الاسترداد، وMidtrans notes الخاصة بالطلب. يظهر التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاسترداد

في تبويب VibeFox Midtrans Payment Gateway أدخل Amount (يُملأ المبلغ الذي لم يُسترد بعد)، واختياريًا Reason (optional)، ثم اضغط Refund via Midtrans. أكّد السؤال Refund this amount through Midtrans? This cannot be undone. الاسترداد الكامل والجزئي مدعومان بالروبية الكاملة؛ ويُرفض أي مبلغ به كسور عشرية. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). يمكنك الاسترداد حتى المبلغ الذي حصّلته Midtrans فعليًا، حتى لو عُدّل الطلب لاحقًا. تُرسل عملية الاسترداد في البيئة التي تمت فيها الدفعة، لذلك يجب تعيين Server Key لتلك البيئة. ولا تسمح Midtrans بالاسترداد عبر API إلا لبعض طرق الدفع والمعاملات المسوّاة. إذا لم تقبل Midtrans الاسترداد، يعرض التبويب الخطأ ولا يُسجَّل أي استرداد؛ عندها استرد من لوحة Midtrans. وتُضاف عملية الاسترداد الناجحة إلى سجل الاسترداد والملاحظات. يضبط الاسترداد الكامل الطلب على Refunded status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، كما في تغيير الحالة اليدوي. ولا يغيّر الاسترداد الجزئي الحالة. ولا تكون عمليات الاسترداد متاحة إلا بعد أن تبلغ Midtrans بأن الدفعة قد تمت تسويتها.

لا ترجع مرتجعات المنتجات في Sales > Returns أموالًا عبر Midtrans.

تصل عمليات الاسترداد التي تتم في لوحة Midtrans عبر الإشعار، وتُضاف تلقائيًا إلى سجل الاسترداد بالسبب Refunded in the Midtrans dashboard. وعندما تُسترد الدفعة كاملة هناك، يحصل الطلب على Refunded status.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Midtrans Payment Gateway هي أول كتلة في Extensions > Extensions > Payments > VibeFox Midtrans Payment Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key واضغط Activate. بعد ذلك تعرض الكتلة المفتاح مُخفى الأجزاء، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها سطر Product: opencart-payment-midtrans ورابط Manage licenses and domains in your account الذي يفتح حسابك في vibefox.net. لا يمكن تغيير المفتاح إلا لمستخدمي الإدارة الذين لديهم صلاحية Modify للإضافة. تتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تذكر الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، اضغط Check now. إذا تعذّر الوصول إلى خادم التراخيص، تواصل الإضافة العمل بآخر حالة معروفة.

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

بدون مفتاح نشط لا يُعرض Midtrans للعملاء عند الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one. ويظل مستخدم الإدارة المسجّل دخوله إلى لوحة الإدارة في المتصفح نفسه يرى طريقة الدفع في المتجر، مع علامة (unlicensed — visible to admins only)، لتتمكن من إعداد الإضافة واختبارها قبل شراء مفتاح. وفي OpenCart 4 لا تتوفر هذه المعاينة: لا يرى المتجر تسجيل دخول الإدارة، لذلك تبقى طريقة الدفع مخفية عن الجميع من دون مفتاح فعّال. بعد فتح صفحة Edit مرة واحدة يظهر تذكير في Dashboard لوحة الإدارة. أغلقه بـ × لإخفائه لمدة 7 أيام. لا تتأثر الطلبات الموجودة: تستمر الدفعات التي بدأت في التأكيد، وتعمل عمليات الاسترداد.

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

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

Midtrans لا تظهر عند الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن Environment المحددة لديها Server Key. تحقق من أن عملة الدفع هي IDR، ومن أن عنوان الدفع ضمن Geo Zone المحددة، ومن أن الطلب يبلغ Total المحدد في الإعدادات. تعرض صفحة الإعدادات تحذيرًا عندما يكون المفتاح مفقودًا أو تكون عملة المتجر غير IDR.

تمت الدفعة لكن الطلب يبقى بلا حالة: الإشعار لا يعمل. تحقق من أن عنوان URL لإشعار الدفع مُعيَّن في لوحة Midtrans للبيئة التي تستخدمها (sandbox أو production)، وأنه مطابق تمامًا للعنوان المعروض في Notification URL، وأنه قابل للوصول: افتحه في متصفح وسيعرض شرحًا موجزًا. فعّل Debug log لرؤية الإشعارات. ويحصل الطلب أيضًا على حالته عندما يعود العميل إلى المتجر بعد الدفع.

يرد الإشعار بـ Invalid signature: لم يُوقَّع الإشعار بـ Server Key الخاص بالاختبار أو بالإنتاج. تحقق من أن المفاتيح في الإعدادات تخص حساب Midtrans نفسه الذي ترسل منه لوحة الإشعارات.

يرد الإشعار بـ Server key not configured: لم يُعيَّن أي Server Key. أدخله في الإعدادات؛ وستعيد Midtrans إرسال الإشعار.

يرد الإشعار بـ Order not found — ignored: معرّف طلب Midtrans لم يُصدره هذا المتجر، مثلًا متجر آخر على حساب Midtrans نفسه. امنح كل متجر Order ID prefix مختلفًا.

يرد الإشعار بـ Environment mismatch — ignored: وُقّع الإشعار بمفتاح البيئة الأخرى غير البيئة التي تمت فيها الدفعة.

يرد الإشعار بـ Verification failed, please retry: تعذّر الوصول إلى واجهة حالة Midtrans. ستعيد Midtrans إرسال الإشعار.

يرد الإشعار بـ Busy, please retry: كانت السلة تُحدَّث بطلب آخر في اللحظة نفسها، أو تعذّر ضبط حالة الطلب. ستعيد Midtrans إرسال الإشعار. انظر إلى السجل لمعرفة السبب.

الطلب في حالة المراجعة: اقرأ Midtrans notes في التبويب. دفعة البطاقة قيد مراجعة الاحتيال، أو لم يتطابق المبلغ أو العملة المدفوعة مع الطلب، أو وصلت الدفعة بعد إلغاء الطلب.

يرى العميل خطأ بعد Confirm Order: انظر إلى حقل Log في صفحة الإضافة؛ تُسجَّل الأخطاء دائمًا. وينتج عن Server Key خاطئ رسالة بأن مدفوعات Midtrans غير متاحة مؤقتًا. تعني Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method. أن الطلب ليس بالروبية الإندونيسية. وتعني This payment method is not available. أن جلسة الدفع لم تعد تطابق الطلب، أو أن طريقة الدفع أُوقفت في الأثناء: على العميل إعادة تحميل صفحة الدفع.

يعود العميل إلى الدفع مع Payment verification failed.: كان رابط العودة ناقصًا أو لا يخص الطلب. ويحصل الطلب مع ذلك على حالته من الإشعار.

لا يوجد نموذج استرداد في التبويب: يوضح التبويب السبب: الدفعة غير مسوّاة بعد، أو مُستردة بالكامل، أو مجموعة المستخدمين لديك لا تملك صلاحية تعديل الإضافة، أو لم يُعيَّن Server Key لبيئة الدفع التي دُفع فيها الطلب.

يفشل الاسترداد: لا تسمح طريقة الدفع أو حالة المعاملة بالاسترداد عبر API؛ استرد من لوحة Midtrans، وسيُسجَّل الاسترداد تلقائيًا على الطلب.

للمطورين: قبل إنشاء معاملة Snap، تُطلق الإضافة حدث OpenCart midtrans_p_snap_payload مع بيانات الطلب والطلب نفسه؛ ولا يمكن تغيير معرّف الطلب ولا المبلغ.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، واضغط Uninstall (الزر الأحمر −) بجوار VibeFox Midtrans Payment Gateway. تُحذف دائمًا مفتاح الترخيص وحالة الترخيص لهذه الإضافة. يحذف OpenCart دائمًا إعدادات الإضافة الخاصة به: Enable/Disable، وSort Order، وGeo Zone، وTotal، وحالات الطلبات في قسم Orders، والتي تعود إلى قيمها الافتراضية عند إعادة التثبيت. وتُحذف أيضًا أحداث OpenCart الخاصة بالإضافة (وفي OpenCart 4 أيضًا الـ startup action الذي يسمح بمرور الإشعار وعودة العميل في وضع الصيانة). إذا كان Delete data on uninstall مفعّلًا، تُحذف بقية إعدادات البوابة (العنوان، والوصف، والبيئة، وServer Keys، وإعدادات الدفع، والتسجيل) والسجل. وإذا كان متوقفًا، تُحفظ لإعادة التثبيت لاحقًا. تبقى مراجع الدفع في Midtrans وعمليات استرداد الطلبات محفوظة دائمًا، لذلك يمكن استرداد الطلبات المدفوعة سابقًا بعد إعادة التثبيت. وتحتفظ الطلبات الموجودة بملاحظات الدفع الخاصة بها.

في OpenCart 4، لإزالة ملفات الإضافة أيضًا، انتقل بعد إلغاء التثبيت إلى Extensions > Installer، واضغط Uninstall (الزر البرتقالي −) بجوار VibeFox Midtrans Payment Gateway في قائمة الإضافات المثبتة، ثم Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

Midtrans علامة تجارية مسجلة لمالكها. هذه الإضافة غير تابعة لـ Midtrans ولا تحظى بتأييدها.