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

المتطلبات

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

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

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

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

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

التثبيت

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

2. عند اكتمال الرفع، انقر على Configure، أو ابحث لاحقًا عن VibeFox Midtrans Payment Gateway في قائمة الوحدات وانقر على Configure.

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

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

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

عند التثبيت تُنشئ الوحدة حالتين للطلب: Awaiting Midtrans payment وMidtrans payment on hold. يعرض PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences. يجب أن تبقى الوحدة مسموحًا بها للعملة IDR.

الإعدادات

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

Midtrans

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

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-.

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

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

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

يُخبر الإشعار متجرك بأن الدفع قد تم. يعرض حقل Notification URL العنوان الذي يجب استخدامه. وعند تفعيل الروابط الودية يبدو هكذا: https://your-shop/module/wcp_midtrans_payment_gateway/webhook، وقد يتضمن رمز لغة مثل /en/. انسخ العنوان تمامًا كما تعرضه الإعدادات، والصقه في 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 واحد. الرقم هو معرّف السلة مع طابع زمني، مثل WC-123-1700000000. يُسمح بالأحرف والأرقام و- _ . ~ فقط، حتى 20 حرفًا؛ وتُحذف الأحرف الأخرى عند الحفظ. تُتجاهل إشعارات المتاجر الأخرى. الافتراضي: WC-.

متقدم

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

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

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

الدفع

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

بعد الدفع يعود العميل إلى متجرك. لا يضع رابط العودة بحد ذاته علامة «مدفوع» على الطلب أبدًا: لا يُعلَّم الطلب مدفوعًا إلا بعد أن تؤكد Midtrans ذلك، إما بالإشعار الموقّع أو باستعلام إلى واجهة حالة Midtrans عندما يعود العميل. عندها يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية مع طريقة الدفع المستخدمة. في حالة الدفع المؤجل تعرض الصفحة: 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. وفي حالة طلب أُغلق دون دفع تعرض: Your Midtrans payment was not completed. Please contact us about this order. وإذا تعذر الوصول إلى Midtrans عند عودة العميل، تعرض صفحة Payment confirmation الرسالة: We are confirming your payment with Midtrans. The order will be updated automatically — please do not pay again. مع زر Check again.

إذا غادر العميل صفحة 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. تُحفظ السلة. وعندما يدفع العميل مجددًا، يُعاد استخدام Snap غير المستخدم أو المعلّق بالمبلغ نفسه. وإذا تغيّر المبلغ، تنتهي صلاحية المعاملة المعلّقة في Midtrans أولًا. وإذا دُفع Snap السابق في هذه الأثناء، يُنشأ الطلب ولا تُنشأ معاملة جديدة. وإذا كان الطلب موجودًا وأُغلق دون دفع، فالرسالة هي: Your Midtrans payment was declined or has expired. Please place a new order or contact us.

إذا تعذّر على 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. ويُكتب السبب التقني في السجل. وتعرض السلة التي ليست بالروبية الإندونيسية الرسالة Midtrans only supports payments in IDR (Indonesian Rupiah). Please choose another payment method.

يعمل الإشعار حتى أثناء وضع الصيانة في المتجر، ولا يتعطل بقيد الدول في متجرك.

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

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

حالات الطلب

No order yet: أُرسل العميل إلى Midtrans ولم يدفع، أو لم تؤكد Midtrans الدفع بعد. لا توجد إلا السلة.

Awaiting Midtrans payment: اختار العميل طريقة مؤجلة (حساب افتراضي، متجر تسوق سريع) أو بدأ دفعة ببطاقة لم تكتمل. يصبح الطلب مدفوعًا عندما تبلغ Midtrans عن الدفع.

Payment accepted أو Delivered أو Midtrans payment on hold: تم تأكيد الدفع. تتبع الحالة Status after payment. يُسجَّل الدفع بمعرّف معاملة Midtrans، وتعرض ملاحظة طريقة الدفع ومعرّف طلب Midtrans.

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

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

Payment error: فشل الدفع، أو رُفضت دفعة بطاقة خضعت للمراجعة.

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

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

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

تعرض صفحة الطلب كتلة Midtrans payment تتضمن معرّف طلب Midtrans، ومعرّف المعاملة (مرتبطًا بالمعاملة في لوحة Midtrans لبيئة الدفع)، وطريقة الدفع، والحالة، والمبلغ المدفوع والمسترد، وشارة Sandbox لمدفوعات sandbox، وسجل الاسترداد، وMidtrans notes الخاصة بالطلب.

الاسترداد

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

لا تُنشئ الوحدة إشعارات ائتمان. وأزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر Midtrans.

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

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

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

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

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

بدون مفتاح نشط لا يظهر Midtrans للعملاء في الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل This payment method is not available. Please choose another one. ولا يعلم متجر PrestaShop أنك مسجّل الدخول إلى الواجهة الخلفية، لذلك تُخفى طريقة الدفع عنك أيضًا: يمكنك إعداد الوحدة قبل شراء المفتاح، لكن لا يمكنك اختبارها عند الدفع. ويظهر تذكير في Modules > Module Manager على تبويب Alerts. ولا تتأثر الطلبات الحالية: فالمدفوعات التي بدأت بالفعل ما زالت تُؤكَّد، والاستردادات تعمل.

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

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

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

The payment went through, but no order was created: الإشعار لا يعمل. تحقق من أن عنوان إشعار الدفع مضبوط في لوحة Midtrans للبيئة التي تستخدمها (sandbox أو production)، وأنه مطابق تمامًا للعنوان الظاهر في Notification URL، وأنه متاح: افتحه في المتصفح، وسيظهر شرح قصير. فعّل Debug log لرؤية الإشعارات. ويُنشأ الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع.

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

Notification answers Server key not configured: لم يُضبط أي Server Key. أدخله في الإعدادات؛ وستعيد Midtrans محاولة الإشعار.

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

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

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

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

The order is Midtrans payment on hold: اقرأ Midtrans notes في الكتلة. دفعة البطاقة قيد مراجعة الاحتيال، أو المبلغ المدفوع أو العملة لا يطابقان الطلب، أو وصل الدفع بعد إلغاء الطلب.

The customer sees an error when choosing Midtrans: انظر إلى حقل Log في صفحة الوحدة؛ تُسجَّل الأخطاء دائمًا. ويعرض Server Key الخاطئ رسالة بأن مدفوعات Midtrans غير متاحة مؤقتًا.

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

يمكن للمطوّرين تغيير البيانات المرسلة إلى Midtrans بالخطاف actionWcpMidtransSnapPayload؛ ولا يمكن تغيير معرّف الطلب والمبلغ.

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

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

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