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

المتطلبات

WordPress: 6.0 أو أحدث.

WooCommerce: 8.0 أو أحدث، مثبّت ومفعّل. بدون WooCommerce لا يمكن تفعيل الإضافة.

PHP: 8.0 أو أحدث.

عملة المتجر: الروبية الإندونيسية (IDR). مع العملات الأخرى تُخفى طريقة الدفع في صفحة الدفع. لا يوجد تحويل عملات.

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

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

التثبيت

1. في WordPress، انتقل إلى Plugins > Add New > Upload Plugin، واختر ملف ZIP الخاص بالإضافة، ثم انقر Install Now. يمكنك أيضًا رفع مجلد wcp_midtrans_payment_gateway إلى /wp-content/plugins/ عبر FTP.

2. انقر Activate.

3. اضبط عملة المتجر على الروبية الإندونيسية (IDR).

4. افتح الإعدادات: WooCommerce > Settings > Payments > Midtrans > Manage، أو انقر Settings أسفل اسم الإضافة في صفحة الإضافات.

5. أدخل مفتاح ترخيص VibeFox في كتلة الترخيص أعلى الصفحة، ثم انقر Activate.

6. أدخل Server Key وانسخ عنوان إشعار الدفع إلى لوحة Midtrans (انظر الإعدادات).

7. فعّل Enable/Disable. اختبر في Sandbox ثم بدّل Environment إلى Production.

الإعدادات

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Midtrans. تُظهر الصفحة فوق الحقول تحذيرًا عند غياب Server Key للبيئة المختارة (فتُخفى طريقة الدفع في صفحة الدفع)، وعند كون عملة المتجر غير IDR، وتعرض Sandbox mode: payments are simulated, no real money is charged. عند اختيار Sandbox. وفي قائمة طرق الدفع، يُعلَّم Midtrans بأنه يحتاج إلى إعداد حتى يُدخل Server Key، ويعرض Test mode في Sandbox.

عام

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

Title: عنوان طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Midtrans.

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

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

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

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

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

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

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

يخبر الإشعار متجرك بأن الدفع قد تمّ. يعرض القسم العنوان الذي يجب استخدامه، وهو بالشكل: https://your-site/wc-api/midtrans_p_callback/. الصقه في Midtrans Dashboard > Settings > Payment > Notification URL في لوحة sandbox ولوحة الإنتاج التي تستخدمها. إذا فتحت العنوان في المتصفح، ستظهر شرح قصير، فتستطيع التحقق من أنه متاح. ويستجيب أيضًا زر Test notification URL في لوحة Midtrans.

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

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

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

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

Status after payment: حالة الطلب بعد دفع مؤكَّد. تُضبط الحالة في خطوة واحدة دون إرسال رسائل بريد مكررة للعميل.

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

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

متقدم

Debug log: Log API calls and notifications يكتب في WooCommerce > Status > Logs، بالمصدر wcp_midtrans_payment_gateway. تُسجَّل الأخطاء دائمًا. ولا تُسجَّل المفاتيح وبيانات العملاء أبدًا. الافتراضي: off.

Delete data on uninstall: Remove the plugin settings and logs when the plugin is deleted (deactivation keeps everything). Order data is kept. الافتراضي: off.

الدفع

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

بعد الدفع يعود العميل إلى صفحة استلام الطلب في متجرك. ورابط العودة وحده لا يُعلّم الطلب كمدفوع أبدًا: تستعلم الإضافة من واجهة برمجة حالة Midtrans، ولا يُعلَّم الطلب كمدفوع إلا بعد أن يؤكده Midtrans. وما دام الدفع غير مؤكَّد، تعرض الصفحة We are waiting for Midtrans to confirm your payment. .... وتعرض الصفحة أيضًا طريقة الدفع المستخدمة.

إذا لم يكتمل الدفع، يُوجَّه العميل إلى صفحة Pay for order مع الرسالة 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.. وعندما يدفع العميل مجددًا، يُعاد استخدام Snap غير المستخدم أو المعلّق بالمبلغ نفسه. وإذا تغيّر المبلغ، تُنهى صلاحية المعاملة المعلّقة لدى Midtrans أولًا. وإذا دُفع Snap السابق في الأثناء، يُؤكَّد الطلب ولا تُنشأ معاملة جديدة.

إذا تعذّر على Midtrans بدء الدفع، يرى العميل الرسالة 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. ويُضاف السبب التقني إلى ملاحظات الطلب.

تعمل طريقة الدفع في صفحة الدفع الكلاسيكية وكتلة Checkout وصفحة Pay for order. وهي متوافقة مع تخزين الطلبات عالي الأداء في WooCommerce (HPOS).

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

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

حالات الطلب

Pending payment: أُرسل العميل إلى Midtrans ولم يختر طريقة دفع بعد.

On hold: اختار العميل طريقة مؤجلة ولم يدفع بعد، أو أن دفعة البطاقة قيد المراجعة الأمنية (challenge)، أو أن المبلغ المدفوع أو العملة لا يطابقان الطلب. ويُعيَّن On hold أيضًا عند وصول دفعة لطلب ملغى؛ ولا يُعاد فتح الطلب تلقائيًا. وتشرح ملاحظة الطلب ذلك.

Processing, Completed or On hold after payment: تم تأكيد الدفع. وتتبع الحالة Status after payment. وتُظهر ملاحظة الطلب طريقة الدفع ومعرّفات Midtrans. ومعرّف المعاملة هو معرّف معاملة Midtrans، ويؤدي في شاشة الطلب إلى المعاملة في لوحة Midtrans الخاصة بالبيئة التي يتبعها الطلب.

Failed: فشل الدفع، أو رُفضت دفعة بطاقة في وضع challenge.

Cancelled: انتهت صلاحية المعاملة غير المدفوعة أو أُلغيت. ويُعاد المخزون. وعند إلغائك طلب Midtrans غير مدفوع في WooCommerce (أو عند قيام مؤقّت الطلبات غير المدفوعة بذلك)، تُنهى صلاحية معاملته المعلّقة لدى Midtrans، مثل حساب افتراضي تم إصداره، فلا يمكن دفعها بعد ذلك.

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

الاستردادات

افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via Midtrans (يعرض الزر Title الخاص بك). الاستردادات الكاملة والجزئية مدعومة بالروبية الصحيحة؛ والمبلغ الذي يحتوي على كسور عشرية مرفوض. يُرسل الاسترداد في البيئة التي دُفع فيها الطلب، لذلك يجب ضبط Server Key لتلك البيئة. ولا يسمح Midtrans بالاسترداد عبر API إلا لبعض طرق الدفع وحالات المعاملات (مثل مدفوعات البطاقات المسوّاة، وGoPay، وQRIS، وShopeePay). وإذا لم يقبل Midtrans الاسترداد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد؛ وعندها نفّذ الاسترداد من لوحة Midtrans. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب.

تصل الاستردادات المنفذة من لوحة Midtrans عبر الإشعار، وتُسجَّل تلقائيًا كاستردادات WooCommerce بالسبب Refunded in the Midtrans dashboard.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. تقع كتلة الترخيص أعلى WooCommerce > Settings > Payments > Midtrans. ألصق المفتاح في License key وانقر Activate. تعرض الكتلة الحالة، مثل تاريخ انتهاء صلاحية الترخيص ونطاقك. استخدم Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالته من هذا الموقع. ويفتح الرابط Manage licenses and domains in your account حسابك في vibefox.net.

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

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

عند انتهاء صلاحية الترخيص، تستمر الإضافة في العمل، لكن التحديثات والدعم تحتاج إلى تجديد. ويُعاد التحقق من الحالة تلقائيًا في الخلفية.

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

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

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

الإشعار يرد بـ Invalid signature: لم يُوقَّع الإشعار بـ Server Key الخاصة بـ Sandbox أو Production. تحقّق من أن المفاتيح في الإعدادات تنتمي إلى حساب 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 محاولة الإشعار.

الطلب في حالة On hold: اقرأ ملاحظة الطلب. لم يُكمل العميل دفعة مؤجلة، أو أن دفعة البطاقة قيد المراجعة الأمنية، أو أن المبلغ المدفوع أو العملة لا يطابقان الطلب.

يرى العميل خطأ عند تقديم الطلب: افتح ملاحظات الطلب، أو فعّل Debug log وراجع WooCommerce > Status > Logs بالمصدر wcp_midtrans_payment_gateway. ويعرض الطلب غير المقوَّم بـ IDR الرسالة Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.

يفشل الاسترداد: طريقة الدفع أو حالة المعاملة لا تسمح بالاسترداد عبر API؛ نفّذ الاسترداد من لوحة Midtrans، وسيُسجَّل الاسترداد في WooCommerce تلقائيًا. وإذا ذكرت الرسالة أنه لم تُضبط أي Server Key للبيئة التي دُفع فيها الطلب، فأدخل ذلك المفتاح وأعد المحاولة.

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

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

إلغاء تفعيل الإضافة يُبقي على جميع البيانات. ولحذفها، ألغِ تفعيلها ثم احذفها من صفحة Plugins. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. أما إعدادات البوابة والسجلات فتُحذف فقط إذا كان Delete data on uninstall مفعّلًا. وإلا تبقى لإعادة التثبيت لاحقًا. وتحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات.

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