VibeFox Peach Payments for WooCommerce — المساعدة

المتطلبات

WordPress: الإصدار 6.2 أو أحدث.

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

PHP: الإصدار 8.0 أو أحدث.

Currency: يجب أن تكون عملة المتجر ZAR أو KES أو MUR. في العملات الأخرى تُخفى وسيلة الدفع وتوضح صفحة الإعدادات ذلك.

Peach Payments account: تحتاج إلى بيانات اعتماد Card API لحسابك لدى Peach Payments: ‏Entity ID وAccess Token. تأتي بيانات الاختبار من لوحة تحكم بيئة اختبار Peach Payments، وبيانات الإنتاج من لوحة تحكم Peach Payments؛ وهي مختلفة. تحتاج webhooks أيضًا إلى مفتاح فك تشفير ترسله Peach Payments عند تفعيل Card webhooks لمتجرك (انظر الإعداد). يجب أن يكون موقعك متاحًا عبر الإنترنت لاستقبال webhooks.

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

التثبيت

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

2. انقر Activate.

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

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

5. أدخل Entity ID وAccess Token للاختبار من لوحة تحكم بيئة اختبار Peach Payments، واطلب من Peach Payments تفعيل Card webhooks لعنوان webhook المعروض في صفحة الإعدادات (انظر الإعداد).

6. فعّل Enable/Disable واحفظ. أبقِ Test mode مفعّلًا ونفّذ دفعة ببطاقة اختبار لبيئة اختبار Peach Payments. ثم ألغِ تحديد Test mode، وأدخل بيانات اعتماد الإنتاج ومفتاح webhook للإنتاج واحفظ.

تُنقل إعدادات الإصدار 1.0 إلى الحقول الجديدة تلقائيًا بعد التحديث.

الإعداد

جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Peach Payments. تظهر فوق الحقول تنبيهات: Test mode is on: payments go to the Peach Payments sandbox and no real money is charged.؛ وتنبيه عند غياب Entity ID أو Access Token للوضع الحالي (لا تظهر وسيلة الدفع حتى إدخالهما)؛ وتنبيه عند غياب مفتاح فك تشفير webhook للوضع الحالي (عندها لا تُؤكَّد الدفعات إلا بعودة العميل إلى المتجر)؛ وتنبيه إذا كانت عملة المتجر غير مدعومة. في قائمة وسائل الدفع، تُعلَّم Peach Payments بأنها تحتاج إلى إعداد حتى يتوفر Entity ID وAccess Token للوضع الحالي. عند الحفظ، تُحذف المسافات من بيانات الاعتماد، ويظهر خطأ إذا لم يكن مفتاح webhook قيمة سداسية عشرية من 64 حرفًا.

Enable/Disable: يشغّل Enable Peach Payments وسيلة الدفع أو يوقفها. الافتراضي: متوقف.

Title: اسم وسيلة الدفع المعروض للعميل في صفحة الدفع. الافتراضي: Credit / Debit Card (Peach Payments).

Description: النص المعروض تحت وسيلة الدفع في صفحة الدفع. الافتراضي: Pay securely with your card. You will enter the card details in the Peach Payments form on the next page.

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

يظهر Access Token وEntity ID لواجهة Card API في لوحة تحكم Peach Payments (بيانات الاختبار في لوحة بيئة الاختبار). يتضمن القسم روابط للوحتَي التحكم ووثائق مطوري Peach Payments.

Test mode: يرسل Enable test mode الدفعات الجديدة إلى بيئة اختبار Peach Payments ببيانات الاختبار، ولا تُخصم أموال حقيقية. ألغِ تحديده لقبول دفعات حقيقية ببيانات الإنتاج. تُفحص الدفعة التي بدأت في وضع ما في الوضع نفسه دائمًا، حتى بعد التبديل. الافتراضي: مفعّل.

Test Entity ID: معرّف Entity ID (قناة 3-D Secure) لحساب بيئة الاختبار.

Test Access Token: رمز وصول bearer لحساب بيئة الاختبار.

Test Webhook Decryption Key: المفتاح السداسي العشري من 64 حرفًا لفك تشفير Card webhooks في بيئة الاختبار.

Live Entity ID: معرّف Entity ID (قناة 3-D Secure) لحساب الإنتاج.

Live Access Token: رمز وصول bearer لحساب الإنتاج.

Live Webhook Decryption Key: المفتاح السداسي العشري من 64 حرفًا لفك تشفير Card webhooks لحساب الإنتاج.

webhook

تؤكد webhooks الدفعات حتى لو أغلق العميل المتصفح قبل العودة إلى المتجر. يعرض القسم عنوان webhook لمتجرك، مثل https://your-site/wp-json/peach-pay/v1/webhook. انسخ العنوان كما يظهر في الإعدادات تمامًا. اطلب من Peach Payments ‏(support@peachpayments.com) تفعيل Card webhooks لحسابك بهذا العنوان، ثم أدخل مفتاح فك التشفير الذي تستلمه في حقل Webhook Decryption Key للوضع نفسه.

تشفّر Peach Payments كل webhook ‏(AES-256-GCM). تُرفض webhook التي لا يمكن فك تشفيرها بمفتاح الاختبار أو الإنتاج، لذا لا يستطيع تغيير طلباتك إلا Peach Payments. وتُطبَّق webhook المفكوكة بمفتاح وضع معين فقط على الدفعات التي بدأت في ذلك الوضع. تستخدم الإضافة إشعارات الدفع:

تتلقى الإشعارات الأخرى، مثل إشعار الاختبار عند تفعيل webhook، رد OK وتُتجاهل. دون مفتاح webhook، لا يُؤكَّد الطلب إلا عند عودة العميل إلى المتجر بعد الدفع.

نموذج الدفع

Card brands: العلامات المعروضة في نموذج Peach Payments: ‏Visa وMastercard وAmerican Express وDiners Club. اختر فقط المفعّلة لمعرّف Entity ID لديك. الافتراضي: Visa وMastercard.

متقدم

Logging: يكتب Log API requests and payment results معلومات التصحيح في WooCommerce > Status > Logs، بالمصدر wcp_peach_pay. تُسجَّل الأخطاء والتحذيرات دائمًا. لا تتضمن السجلات بيانات البطاقات أو المفاتيح أو بيانات العملاء. الافتراضي: متوقف.

Delete data on uninstall: Delete the plugin settings and logs when the plugin is deleted. تعطيل الإضافة لا يحذف أي شيء أبدًا. تُحفظ بيانات Peach Payments المخزنة في الطلبات. الافتراضي: متوقف.

الدفع

يختار العميل وسيلة الدفع (افتراضيًا Credit / Debit Card (Peach Payments)) وينقر Continue to payment. ينتقل إلى صفحة Pay for order في متجرك. هناك تُنشئ الإضافة عملية دفع Peach Payments بإجمالي الطلب وعملته، وتعرض نموذج البطاقة من Peach Payments بالعلامات المختارة وبلغة الموقع إذا كانت Peach Payments تدعمها. في وضع الاختبار تعرض الصفحة Test mode: use a Peach Payments test card, no real payment will be made.. تُدخل بيانات البطاقة في نموذج Peach Payments، ويُحمّل البرنامج النصي مع قيمة تجزئة Subresource Integrity.

بعد الدفع، يعود العميل إلى متجرك. لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Peach Payments: يقرأ المتجر نتيجة عملية الدفع لهذا الطلب من Peach Payments API في الوضع الذي أُنشئت فيه، ويتحقق من انتماء الدفعة لهذا الطلب. تنفّذ webhook الأمر نفسه بشكل مستقل؛ يصل الأول فيطبّق النتيجة، ولا يغيّر الآخر شيئًا. يرى العميل الذي دفع صفحة Order received.

إذا لم يكتمل الدفع، يعود العميل إلى صفحة Pay for order مع رسالة ويمكنه المحاولة مجددًا: Payment failed: يتبعها السبب من Peach Payments وPlease try again or use another card.، أو The payment was not completed. Please try again.. إذا تعذّر تأكيد النتيجة بعد (مثل عدم رد Peach Payments أو معالجة webhook للطلب نفسه حاليًا)، تكون الرسالة We could not confirm your payment yet. If you were charged, the order will be updated automatically; otherwise please try again.. إذا لم يُضبط مفتاح webhook لهذا الوضع، يُطلب من العميل بدلًا من ذلك التواصل معك برقم الطلب.

إذا تعذّر إعداد النموذج، يرى العميل رسالة قصيرة وزر Try again: ‏The payment form is not available right now (payment configuration error). Please contact us or choose another payment method. (بيانات اعتماد خاطئة)، أو رسالة بأن مزود الدفع لم يقبل بعض بيانات الفوترة، أو The payment form could not be loaded. Please try again in a moment.. تُضاف إلى الطلب ملاحظة برمز Peach Payments ووصفه.

تعمل الوسيلة في صفحة الدفع الكلاسيكية وكتلة Checkout وصفحة Pay for order. وهي متوافقة مع WooCommerce High-Performance Order Storage ‏(HPOS).

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

الطلبات

حالات الطلب

Pending payment: لم يدفع العميل بعد أو لم يكتمل الدفع. يمكنه دفع الطلب نفسه مجددًا.

Processing: تأكد الدفع وطابق المبلغ والعملة الطلب. تعرض الملاحظة رمز نتيجة Peach Payments ووصفها ومعرّف الدفع؛ وهو معرّف معاملة الطلب. إذا علّمت Peach Payments الدفعة للمراجعة اليدوية، تطلب الملاحظة فحصها في لوحة تحكم Peach Payments قبل الشحن.

On hold: تنتظر الدفعة تأكيد Peach Payments (تُكملها webhook لاحقًا أو تعلّمها كفاشلة)؛ أو يختلف المبلغ المدفوع أو العملة عن الطلب (الملاحظة amount/currency mismatch — manual review required)؛ أو وصلت الدفعة بعد إلغاء الطلب. توضح الملاحظة ما يجب فحصه.

Failed: رفضت Peach Payments دفعة طلب بانتظار الدفع أو الدفعة التي كان ينتظرها طلب قيد الانتظار. لا تغيّر المحاولة المرفوضة طلبًا مدفوعًا أو معلّقًا لسبب آخر أو ملغى. يمكن للعميل الدفع مجددًا.

إذا نجحت دفعة ثانية لطلب مدفوع، فلا يتغير الطلب. توضح ملاحظة أنها دفعة مكررة وتطلب استردادها من لوحة تحكم Peach Payments. الدفعة التي تصل لطلب مسترد لا تُسجَّل إلا كملاحظة.

الاستردادات

لا يتوفر الاسترداد من شاشة طلب WooCommerce. استرد الدفعة في لوحة تحكم Peach Payments وسجّل استردادًا يدويًا في WooCommerce. عند إعداد webhook، تُضاف الاستردادات والعكس وعمليات رد المبالغ القسري في Peach Payments كملاحظات تتضمن المبلغ والمعرّف؛ ولا تتغير حالة الطلب.

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

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

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

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

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

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

لا يظهر Peach Payments في صفحة الدفع: تأكد من نشاط الترخيص وتفعيل Enable/Disable وإدخال Entity ID وAccess Token للوضع الحالي (Test Entity ID وTest Access Token للاختبار، وLive Entity ID وLive Access Token للإنتاج)، وأن العملة ZAR أو KES أو MUR. تحدد التنبيهات أعلى الإعدادات المشكلة. يمكن للمطورين تغيير العملات بمرشح peach_p_supported_currencies؛ أضف فقط العملات التي يعالجها حساب Peach Payments لديك.

تم الدفع لكن الطلب ما زال Pending payment: لم يعد العميل ولم تصل webhook. تأكد من تفعيل Peach Payments لـ Card webhooks على العنوان المطابق تمامًا للإعدادات، وإدخال Webhook Decryption Key لوضع الدفع، وألا يمنع وضع الصيانة أو الجدار الناري أو كلمة المرور الوصول للعنوان. افحص webhooks المرفوضة في WooCommerce > Status > Logs، بالمصدر wcp_peach_pay.

ترد webhook بالرسالة Decryption failed: تعذّر فك تشفيرها بمفتاح الاختبار أو الإنتاج. المفتاح خاطئ أو يخص حسابًا أو وضعًا آخر. أدخل المفتاح الذي أرسلته Peach Payments لهذا العنوان.

ترد webhook بالرسالة Webhook key not configured: لم يُضبط أي مفتاح صالح. أدخل المفتاح المكوّن من 64 حرفًا. تعيد Peach Payments إرسال webhook لاحقًا.

ترد webhook بالرسالة Order busy, retry later: كان الطلب يُحدَّث بعودة العميل في الوقت نفسه. لم يتغير شيء وتعيد Peach Payments إرسال webhook.

ترد webhook بالرسالة Missing or malformed data: افتقر الطلب إلى محتوى مشفّر أو ترويسات X-Initialization-Vector / X-Authentication-Tag، مثلًا بسبب تعديل وكيل وسيط. لم يتغير شيء.

ترد webhook بالرسالة ignored: الإشعار أصلي لكنه لا يخص عملية دفع لهذا المتجر (متجر آخر على Entity ID نفسه، طلب محذوف)، أو جاء من وضع مختلف عن الدفع. لم يتغير شيء.

يرى العميل The payment form is not available right now: ‏Access Token أو Entity ID للوضع الحالي خاطئ. افحص بيانات الاعتماد والوضع واقرأ رمز Peach Payments في ملاحظة الطلب.

الطلب On hold بعد الدفع: اقرأ الملاحظة. اختلف المبلغ أو العملة، أو وصلت الدفعة بعد الإلغاء، أو لا تزال Peach Payments تنتظر التأكيد. افحص الدفعة في لوحة تحكم Peach Payments ثم عالج الطلب أو استرد الدفعة.

يطلب الحفظ مفتاح webhook سداسيًا عشريًا من 64 حرفًا: القيمة ليست مفتاح Peach Payments. لا يمكن فك تشفير webhooks حتى تصحيحها.

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

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

يحفظ تعطيل الإضافة جميع البيانات. لإزالتها، عطّلها واحذفها من صفحة Plugins. يُزال مفتاح ترخيص الإضافة وحالته دائمًا. لا تُزال الإعدادات والسجلات (ملفات السجل ومدخلاته في قاعدة البيانات للمصدر wcp_peach_pay) إلا إذا كان Delete data on uninstall مفعّلًا. وإلا تبقى لإعادة التثبيت لاحقًا. تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات وبيانات عملية الدفع لدى Peach Payments.

Peach Payments علامة تجارية لمالكها المعني. هذه الإضافة غير تابعة لـ Peach Payments ولا معتمدة منها.