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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

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

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

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

التثبيت

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

2. انقر Activate.

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

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

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

6. فعّل Enable/Disable. أجرِ طلبًا تجريبيًا في وضع الاختبار، ثم ألغِ تحديد Test Mode لقبول مدفوعات حقيقية.

الإعداد

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Xendit. يعرض شريط فوق الحقول الوضع النشط: 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: Enable test mode ينشئ الفواتير بالمفتاح السري للاختبار، لذلك لا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل. ألغِ تحديده لقبول مدفوعات حقيقية بالمفتاح السري للإنتاج.

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

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

Webhooks

يُخبر الـ webhook متجرك بأن فاتورة قد دُفعت. في Xendit Dashboard > Settings > Developers > Webhooks، اضبط عنوان URL المعروض في هذا القسم من الإعدادات لـ Invoices > Invoice paid، في وضع الاختبار وفي وضع الإنتاج. ويمكنك اختياريًا ضبطه لـ Invoice expired أيضًا. يبدو عنوان URL هكذا: https://your-site/wc-api/xendit_p_callback/. انسخه تمامًا كما تعرضه الإعدادات.

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

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

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

الدفع

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

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

متقدم

Debug Log: Log API requests and webhooks يكتب الطلبات والـ webhooks وتغييرات الحالة في WooCommerce > Status > Logs، بالمصدر wcp_xendit_payment_gateway. تُسجَّل الأخطاء والتحذيرات دائمًا، حتى عندما يكون هذا الخيار معطّلًا. لا تُسجَّل المفاتيح السرية ولا الرموز ولا بيانات العملاء. الافتراضي: معطّل.

Delete Data on Uninstall: Delete the plugin settings and logs when the plugin is deleted. تعطيل الإضافة لا يحذف أي شيء أبدًا. تُحتفظ بيانات الطلبات (معرّفات الفواتير في الطلبات) دائمًا. الافتراضي: معطّل.

الدفع

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

بعد الدفع، يعود العميل إلى صفحة «الطلب المستلم» في متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده Xendit: عبر الـ webhook، أو بطلب من جهة الخادم إلى واجهة Xendit البرمجية عندما يصل العميل إلى تلك الصفحة. وحتى ذلك الحين يبقى الطلب في حالة «في انتظار الدفع».

إذا فشلت الفاتورة أو انتهت صلاحيتها، تُعيد Xendit العميل. يُلغى الطلب الذي أُجري في صفحة الدفع بالطريقة القياسية في WooCommerce، وتنتهي صلاحية فاتورته. أما الطلب المدفوع من صفحة Pay for order (مثل طلب أنشأته للعميل)، فيعود إلى صفحة الدفع الخاصة به مع الرسالة 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.

تعمل طريقة الدفع في الدفع الكلاسيكي، وفي كتلة Checkout، وفي صفحة Pay for order. وفي وضع الاختبار، تعرض كتلة Checkout عبارة Test mode: no real money is charged. أسفل طريقة الدفع. وهي متوافقة مع WooCommerce High-Performance Order Storage (HPOS).

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

الطلبات

حالات الطلب

Pending payment: أُنشئت الفاتورة ولم يدفع العميل بعد، أو لم تؤكد Xendit الدفع بعد. تعرض ملاحظة الطلب معرّف الفاتورة والمبلغ والعملة والوضع.

Processing or Completed: تم تأكيد الدفع. تتبع الحالة Order Status After Payment. تعرض ملاحظة الطلب معرّف الفاتورة والمبلغ المدفوع وقناة الدفع والوضع. ومعرّف المعاملة هو معرّف فاتورة Xendit.

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

Failed: انتهت صلاحية الفاتورة الحالية دون دفع. يمكن للعميل دفع الطلب مرة أخرى.

Cancelled: عاد العميل من فاتورة فاشلة أو منتهية الصلاحية، أو أُلغي الطلب من قِبلك أو بسبب مهلة WooCommerce للطلبات غير المدفوعة. تنتهي صلاحية الفاتورة المفتوحة، فلا يمكن دفعها بعد ذلك. وإذا لم تقبل Xendit ذلك، تطلب منك ملاحظة إنهاء صلاحية الفاتورة في لوحة تحكم Xendit.

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

الاستردادات

لا تُرسل الاستردادات من WooCommerce إلى Xendit. استرد الدفعة في لوحة تحكم Xendit (تحتوي ملاحظة الطلب ومعرّف المعاملة على معرّف الفاتورة)، ثم سجّل الاسترداد في WooCommerce يدويًا.

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

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

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

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

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

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

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

تمت عملية الدفع لكن الطلب ما زال في حالة «في انتظار الدفع»: الـ webhook لا يعمل. في لوحة تحكم Xendit للوضع الذي تستخدمه (الاختبار أو الإنتاج)، تحقق من أن عنوان 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 هذا الرد أيضًا، وهذا يؤكد أن عنوان URL والرمز يعملان.

رد الـ webhook «Temporary error»: تعذّر الوصول إلى واجهة Xendit البرمجية للتحقق من الفاتورة، أو المفتاح السري لوضع الفاتورة مفقود، أو كان طلب آخر يحدّث الطلب في اللحظة نفسها. تعيد Xendit محاولة الـ webhook. إذا كانت لديك طلبات من الوضعين، فتحقق من ضبط المفتاحين السريين.

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

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

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

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

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

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

تعطيل الإضافة يحتفظ بجميع البيانات. للإزالة، عطّلها واحذفها من صفحة Plugins. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. أما إعدادات البوابة والخيارات الأخرى للإضافة والبيانات المؤقتة وسجلاتها (ملفات السجل بما فيها الملفات المؤرشفة، وإدخالات السجل في قاعدة البيانات، ومجلد السجلات للإصدار 1.0)، فلا تُحذف إلا إذا كان Delete Data on Uninstall مفعّلًا. وإلا تبقى لإعادة التثبيت لاحقًا. تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات الفواتير ومعرّفات المعاملات.

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