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

المتطلبات

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

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

عملة المتجر: IDR أو PHP أو VND أو THB أو MYR أو USD أو SGD. لا تظهر طريقة الدفع لعملات السلة الأخرى. أما قنوات الدفع والعملات المتاحة فعليًا فتعتمد على حسابك لدى Xendit.

حساب Xendit: تحتاج إلى مفتاح API سري بصلاحية الكتابة لـ Money-in (الفواتير) لوضع الاختبار، ومفتاح آخر لوضع الإنتاج، إضافة إلى رمز التحقق من webhook لكل وضع (راجع الإعدادات). لا تُستخدم إلا المفاتيح السرية ورموز التحقق. ولا حاجة إلى مفتاح عام، لأن العميل يدفع في صفحة الفاتورة المستضافة لدى Xendit.

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

التثبيت

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

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

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

4. الصق المفاتيح السرية لـ Xendit، واضبط عنوان webhook في لوحة تحكم Xendit، والصق رموز التحقق (راجع الإعدادات).

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

عند التثبيت تُنشئ الوحدة حالة الطلب Xendit payment on hold. تقدم PrestaShop وحدة دفع جديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences.

الإعدادات

جميع الإعدادات موجودة في صفحة الوحدة: Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure. لكل قسم زر Save خاص به، وهو يحفظ الصفحة كلها. يعرض مربع فوق الحقول الوضع النشط: TEST MODE (تُنشأ الفواتير بالمفتاح السري للاختبار ولا يُحصَّل أي مبلغ حقيقي) أو LIVE MODE (تُنشأ الفواتير بالمفتاح السري للإنتاج ويُحصَّل المبلغ من العملاء). يحذّرك المربع عندما يكون المفتاح السري للوضع النشط مفقودًا أو ذا بادئة خاطئة (وعندها تُخفى طريقة الدفع في صفحة الدفع)، وعندما يكون رمز التحقق من webhook للوضع النشط فارغًا (فتُرفض إشعارات Xendit، ولذلك لا تُنشأ الطلبات إلا عندما يعود العميل إلى متجرك).

Xendit

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

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

Description: النص الذي يظهر أسفل طريقة الدفع في صفحة الدفع. الافتراضي: Pay with virtual accounts, e-wallets, QR codes, retail outlets or cards via Xendit.

مفاتيح API

أنشئ مفتاح API سريًا بصلاحية الكتابة لـ Money-in (الفواتير) في Xendit Dashboard > Settings > Developers > API keys، مرة في وضع الاختبار ومرة في وضع الإنتاج. يحدد المفتاح المكان الذي تُنشأ فيه الفاتورة. عند الحفظ، لا يُحفظ المفتاح الذي لا يبدأ ببادئة حقله، وتعرض الصفحة مثلًا Test secret key was not saved: it must start with xnd_development_. تُحفظ الإعدادات الأخرى.

Test Mode: ينشئ الفواتير بالمفتاح السري للاختبار، لذلك لا يُحصَّل أي مبلغ حقيقي. الافتراضي: مفعّل. أوقفه لقبول مدفوعات حقيقية بالمفتاح السري للإنتاج. وطالما هو مفعّل يرى العملاء Test mode: no real money is charged. أسفل طريقة الدفع.

Test Secret Key: المفتاح السري لوضع الاختبار في Xendit. يبدأ بـ xnd_development_.

Live Secret Key: المفتاح السري لوضع الإنتاج في Xendit. يبدأ بـ xnd_production_.

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

Webhooks

يخبر webhook متجرك بأن فاتورة قد دُفعت. في Xendit Dashboard > Settings > Developers > Webhooks، اضبط العنوان المعروض في Webhook URL من هذا القسم لـ Invoices > Invoice paid، في وضع الاختبار وفي وضع الإنتاج. ويمكنك اختياريًا ضبطه لـ Invoice expired أيضًا. وعند تفعيل الروابط الودية يكون بالشكل https://your-shop/module/wcp_xendit_payment_gateway/webhook، وقد يحمل رمز لغة مثل /en/. انسخه تمامًا كما تعرضه الإعدادات.

ثم انسخ Webhook verification token لكل وضع من لوحة تحكم Xendit إلى الحقل المطابق له. ترسله Xendit في ترويسة x-callback-token. تُرفض الإشعارات التي لا تحمل رمز الوضع الذي أُنشئت فيه الفاتورة. ولا يثبت الرمز إلا أن الإشعار صادر من Xendit: تُعاد دائمًا قراءة حالة الفاتورة ومبلغها وعملتها من واجهة Xendit البرمجية باستخدام المفتاح السري لذلك الوضع. وبدون webhook لا يُنشأ الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع.

Test Webhook Verification Token: رمز التحقق من webhook لوضع الاختبار في Xendit.

Live Webhook Verification Token: رمز التحقق من webhook لوضع الإنتاج في Xendit.

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

الدفع

Invoice Description: الوصف الذي يظهر على فاتورة Xendit. يمكنك استخدام العناصر النائبة {order_id} و{order_number} و{site_name}. ولأن الطلب يُنشأ بعد الدفع، فإن {order_id} و{order_number} هما رقم السلة. تُحذف HTML ويُقتطع النص عند 255 حرفًا. الافتراضي: Order #{order_id}.

Order Status After Payment: حالة الطلب التي تُعيَّن بعد أن تؤكد Xendit الدفع.

خيارات متقدمة

Debug Log: يكتب طلبات API وwebhooks في logs/xendit_p_debug.log.php داخل مجلد الوحدة. ولا يمكن فتح الملف من الويب. وتُسجَّل الأخطاء والتحذيرات دائمًا حتى عندما يكون هذا الخيار معطّلًا. لا تُسجَّل المفاتيح السرية ولا الرموز ولا بيانات العملاء. الافتراضي: معطّل.

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

Delete Data on Uninstall: عند التفعيل، يؤدي إلغاء تثبيت الوحدة إلى حذف إعداداتها والسجل. أما بيانات الطلبات (معرّفات فواتير الطلبات) وحالة الطلب Xendit payment on hold فتبقى دائمًا. الافتراضي: معطّل.

صفحة الدفع

تظهر طريقة الدفع عندما تكون عملة السلة IDR أو PHP أو VND أو THB أو MYR أو USD أو SGD. يختارها العميل في خطوة الدفع (افتراضيًا Xendit) ويؤكد. تُنشئ الوحدة فاتورة Xendit بإجمالي السلة وبعملة السلة، وتُرسل العميل إلى صفحة فاتورة Xendit. تُقرَّب مبالغ IDR وVND إلى أعداد صحيحة لأن Xendit لا تقبل الكسور العشرية لهذه العملات. يُمرَّر بريد العميل الإلكتروني إلى Xendit. وفي صفحة الفاتورة يدفع العميل عبر إحدى قنوات الدفع المفعّلة في حسابك لدى Xendit لهذه العملة، مثل حساب افتراضي أو محفظة إلكترونية أو رمز QR أو منفذ بيع بالتجزئة أو بطاقة. لا يوجد طلب في هذه المرحلة.

بعد الدفع يعود العميل إلى متجرك. لا يُعلَّم الطلب على أنه مدفوع إلا بعد أن تؤكد Xendit ذلك: عبر webhook، أو بطلب من الخادم إلى واجهة Xendit البرمجية عند عودة العميل. عندها يُنشأ الطلب ويرى العميل صفحة تأكيد الطلب القياسية. وإذا لم تؤكد Xendit الدفع بعد، تظهر صفحة Payment confirmation مع الرسالة Your payment has not been confirmed by Xendit yet. Your order will be created as soon as Xendit confirms it — please do not pay again. وزرّي Check again وBack to checkout. وينشئ webhook الطلب فور وصوله.

إذا فشلت الفاتورة أو انتهت صلاحيتها، تعيد Xendit العميل. تتحقق الوحدة أولًا من الفاتورة (ربما دُفعت في تبويب آخر)، ثم تُنهي صلاحيتها بحيث لا يمكن دفعها بعد ذلك. يعود العميل إلى صفحة الدفع مع الرسالة The Xendit payment was not completed. You can try again or choose another payment method. وتبقى السلة محفوظة.

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

إذا تعذّر على Xendit بدء الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة، مثل Xendit is temporarily unavailable. Please try again in a few minutes or choose another payment method.، أو رسالة تفيد بأن العملة غير مقبولة لحسابك، أو بأن إجمالي الطلب خارج حدود المبالغ لدى Xendit. ويُكتب السبب الفني في السجل. ولا يمكن دفع سلة إجماليها صفر عبر Xendit.

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

يتم الدفع دائمًا في صفحة Xendit. لا تتضمن الوحدة استردادات من لوحة الإدارة، ولا بطاقات محفوظة، ولا اشتراكات أو مدفوعات متكررة، ولا حقول بطاقة أو محفظة إلكترونية في صفحة الدفع، ولا تفويضًا وتحصيلًا منفصلين، ولا حسابات فرعية من xenPlatform.

الطلبات

حالات الطلب

لا يوجد طلب بعد: أُرسل العميل إلى Xendit ولم يدفع بعد، أو لم تؤكد Xendit الدفع بعد. لا توجد إلا السلة.

Payment accepted or Delivered: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. يُسجَّل الدفع بمعرّف فاتورة Xendit بوصفه معرّف المعاملة، وتعرض ملاحظة معرّف الفاتورة والمبلغ المدفوع وقناة الدفع والوضع.

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

إذا دُفعت فاتورة لطلب ملغى أو مُستردّ بالفعل، فلا تتغير حالة الطلب. وتطلب منك ملاحظة استرداد الدفعة في لوحة تحكم Xendit أو استعادة الطلب يدويًا. وإذا دُفعت فاتورة ثانية لطلب مدفوع بالفعل، فلا يتغير الطلب وتطلب منك الملاحظة استرداد الدفعة المكررة في لوحة تحكم Xendit.

كتلة Xendit payment

تعرض صفحة الطلب كتلة Xendit payment تتضمن معرّف الفاتورة، والوضع (مع شارة Test mode لمدفوعات الاختبار)، وحالة الدفع، وقائمة بجميع فواتير الطلب (التاريخ والفاتورة والمعرّف الخارجي والمبلغ والمبلغ المدفوع والحالة وقناة الدفع)، وكذلك Payment notes الخاصة بالطلب.

الاستردادات

لا تُرسل الاستردادات من المتجر إلى Xendit. استرد الدفعة في لوحة تحكم Xendit (ابحث بمعرّف الفاتورة المعروض في كتلة Xendit payment)، وسجّل الاسترداد في الطلب يدويًا. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر Xendit.

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

تعمل الوحدة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Xendit Payment Gateway هي أول كتلة في صفحة Modules > Module Manager > VibeFox Xendit Payment Gateway > Configure، فوق الإعدادات. أدخل المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مقنّعًا، والحالة (مثل تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وتحتها السطر Product: presta-payment-xendit والرابط 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.

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

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

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

لا يظهر Xendit في صفحة الدفع: تحقق من أن الترخيص نشط، وأن Enable/Disable مفعّل، وأن الوضع النشط لديه مفتاح سري بالبادئة الصحيحة (Test Secret Key ببادئة xnd_development_ في وضع الاختبار، وLive Secret Key ببادئة xnd_production_ في وضع الإنتاج)، وأن عملة السلة هي IDR أو PHP أو VND أو THB أو MYR أو USD أو SGD. تعرض صفحة الإعدادات تحذيرًا عندما يكون المفتاح مفقودًا أو خاطئًا. وفي Payment > Preferences تحقق من أن الوحدة مسموح بها لعملة السلة ودولة العميل ومجموعة العميل.

تمت عملية الدفع لكن لم يُنشأ أي طلب: لا يعمل webhook. في لوحة تحكم Xendit للوضع الذي تستخدمه (الاختبار أو الإنتاج)، تحقق من أن العنوان المعروض في Webhook URL مضبوط لـ Invoice paid، وأن رمز التحقق لذلك الوضع محفوظ في الحقل المطابق. وتعرض لوحة تحكم Xendit رد متجرك على كل webhook. ويُنشأ الطلب أيضًا عندما يعود العميل إلى المتجر بعد الدفع.

يرد webhook بالرسالة Webhook verification token is not configured: لم يُضبط أي رمز تحقق. الصق الرمز في الإعدادات.

يرد webhook بالرسالة Unauthorized: الرمز الذي أرسلته Xendit لا يطابق أي رمز في الإعدادات. انسخ رمز الوضع الصحيح مرة أخرى.

يرد webhook بالرسالة Token does not match the mode of this invoice: أُنشئت الفاتورة في الوضع الآخر. لا يؤكد الإشعار الاختباري دفعة حقيقية أبدًا، والعكس صحيح. اضبط webhook والرمز في الوضع الذي دُفعت فيه السلة.

يرد webhook بالرسالة Ignored: not an invoice of this store: لم يُنشئ هذا المتجر الفاتورة، مثلًا أنشأتها تكاملات أخرى على حساب Xendit نفسه. ويتلقى زر Test في لوحة تحكم Xendit الرد نفسه، وهذا يؤكد أن العنوان والرمز يعملان. أما Ignored: unknown order وIgnored: unknown invoice فتعنيان أن هذا المتجر لا يعرف السلة أو الفاتورة.

يرد webhook بالرسالة Temporary error: تعذّر الوصول إلى واجهة Xendit البرمجية للتحقق من الفاتورة، أو المفتاح السري لوضع الفاتورة مفقود، أو كانت السلة تُحدَّث بطلب آخر في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا الوحدة معطّلة). تعيد Xendit إرسال webhook. إذا بدأت مدفوعات في الوضعين، تحقق من ضبط المفتاحين السريين، وفعّل Debug Log لمعرفة السبب.

يعرض عنوان webhook الرسالة Method not allowed في المتصفح: هذا طبيعي. لا يقبل العنوان إلا الطلبات الواردة من Xendit.

لا يُحفظ مفتاح: القيمة لا تبدأ ببادئة حقلها. تبدأ مفاتيح الاختبار بـ xnd_development_، وتبدأ مفاتيح الإنتاج بـ xnd_production_.

يرى العميل الرسالة This payment method is temporarily unavailable: رفضت Xendit الطلب، مثلًا لأن المفتاح السري خاطئ أو لا يملك صلاحية الكتابة لـ Money-in (الفواتير). راجع حقل Log في صفحة الوحدة. والرسالة المتعلقة بتفاصيل الفوترة تعني أن Xendit لم تقبل بيانات الطلب، مثل البريد الإلكتروني.

يرى العميل الرسالة A payment for this order was already received by Xendit and is being reviewed: دُفعت فاتورة سابقة لهذه السلة، لكن لم يتسنَّ تأكيد الطلب بعد. تحقق من الدفع في لوحة تحكم Xendit وفي السجل.

يرى العميل الرسالة We could not match this payment to an order: رابط العودة من Xendit لا يتبع لأي سلة في هذا المتجر، أو تعذّرت مطابقة أي فاتورة للسلة. تحقق من الدفع في لوحة تحكم Xendit وفي السجل.

الطلب في حالة Xendit payment on hold بعد الدفع: اقرأ الملاحظات في كتلة Xendit payment. كان المبلغ المدفوع أو العملة مختلفًا عن السلة. أكمل الطلب أو استرد الدفعة في لوحة تحكم Xendit.

للمطورين، تقدم الوحدة الخطافات actionWcpXenditInvoiceRequest وactionWcpXenditSupportedCurrencies وactionWcpXenditCurrencyDecimals لتعديل طلب الفاتورة، وقائمة العملات، وعدد المنازل العشرية لكل عملة.

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

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

Xendit علامة تجارية مملوكة لصاحبها. هذه الوحدة غير تابعة لـ Xendit ولا معتمدة من قِبلها.