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

المتطلبات

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

PHP: 8.0 أو أحدث مع امتداد OpenSSL (يُستخدم لفك تشفير webhooks). لا تُثبَّت الوحدة دونهما.

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

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

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

التثبيت

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

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

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

4. أدخل Entity ID وAccess Token الخاصين بالاختبار من لوحة sandbox في Peach Payments، واطلب من Peach Payments تفعيل webhooks البطاقات لعنوان webhook المعروض في صفحة الإعدادات (راجع الإعدادات).

5. فعّل Enable/Disable وانقر على Save. أبقِ Test mode مفعّلًا، ونفّذ دفعة ببطاقة اختبار sandbox من Peach Payments. ثم عطّل Test mode، وأدخل بيانات الإنتاج ومفتاح webhook الخاص بالإنتاج، وانقر على Save.

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

الإعدادات

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

Peach Payments

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 credentials

يظهر Access Token وEntity ID الخاصان بـ Card API في لوحة Peach Payments (بيانات الاختبار في لوحة sandbox). ويحتوي القسم على روابط إلى اللوحتين وإلى وثائق المطوّرين في Peach Payments.

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

Test Entity ID: ‏Entity ID (قناة 3-D Secure) لحساب sandbox الخاص بك.

Test Access Token: رمز الوصول من نوع bearer لحساب sandbox الخاص بك.

Test Webhook Decryption Key: المفتاح السداسي العشري المكوّن من 64 خانة والمستخدم لفك تشفير webhooks البطاقات في sandbox.

Live Entity ID: ‏Entity ID (قناة 3-D Secure) لحساب الإنتاج الخاص بك.

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

Live Webhook Decryption Key: المفتاح السداسي العشري المكوّن من 64 خانة والمستخدم لفك تشفير webhooks البطاقات في حساب الإنتاج الخاص بك.

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

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

Webhook

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

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

تتلقى الإشعارات الأخرى، مثل إشعار الاختبار المُرسل عند تفعيل webhook، الرد ignored. ومن دون مفتاح webhook، لا يُنشأ الطلب إلا عندما يعود العميل إلى المتجر بعد الدفع.

Payment form

Card brands: العلامات التي تظهر في نموذج Peach Payments: Visa وMastercard وAmerican Express وDiners Club. اختر فقط العلامات المفعّلة لـ Entity ID الخاص بك. الافتراضي: Visa وMastercard. إذا لم تُختر أي علامة، يظهر تحذير عند الحفظ ويعرض النموذج Visa وMastercard.

Advanced

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

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

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

الدفع

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

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

إذا لم تكتمل الدفعة، يعود العميل إلى صفحة الدفع برسالة ويمكنه المحاولة مرة أخرى: 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 مضبوطًا لوضع الدفعة، يُطلب من العميل التواصل معك بدلًا من ذلك.

إذا تعذّر تجهيز نموذج الدفع، يبقى العميل في صفحة الدفع مع رسالة قصيرة: 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. ويُكتب السبب الفني في السجل.

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

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

الطلبات

حالات الطلب

No order yet: لم يدفع العميل، أو رُفضت الدفعة أو لم تكتمل، أو لم تؤكدها Peach Payments بعد. لا توجد سوى السلة، ويمكن للعميل الدفع مرة أخرى.

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

Awaiting Peach Payments payment: أبلغت Peach Payments عن دفعة تنتظر التأكيد. ثم تنقل webhook الطلب إلى Payment accepted أو تعلّمه كفاشل.

Peach Payments payment on hold: المبلغ المدفوع أو العملة يختلف عن السلة (ملاحظة: amount/currency mismatch — manual review required)، أو وصلت الدفعة بعد إلغاء الطلب. تشرح الملاحظة ما يجب التحقق منه. تحقق من الدفعة في لوحة Peach Payments، ثم عالج الطلب أو استرد الدفعة.

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

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

كتلة الدفع في Peach Payments

تعرض صفحة الطلب كتلة Peach Payments payment تتضمن معرّف الدفعة، ومعرّف الدفع (checkout)، ومعرّف معاملة التاجر، والمبلغ المرسل إلى Peach Payments، والنتيجة ورمزها، وشارة Test mode للدفعات التجريبية، وملاحظات Peach Payments notes الخاصة بالطلب.

الاسترداد

الاسترداد من صفحة طلب PrestaShop غير متاح. استرد الدفعة في لوحة Peach Payments، وسجّلها في PrestaShop (استرداد جزئي أو إشعار دائن) عند الحاجة. وعند إعداد webhook، تُضاف عمليات الاسترداد والعكس وعمليات رد المبالغ القسري المنفذة في Peach Payments إلى ملاحظات الطلب مع المبلغ والمعرّف؛ ولا تتغير حالة الطلب.

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

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

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

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

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

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

تمت الدفعة لكن لم يُنشأ أي طلب: لم يعد العميل إلى المتجر، ولم يصل webhook. تحقق من أن Peach Payments فعّلت webhooks البطاقات للعنوان المعروض في الإعدادات تمامًا، وأن Webhook Decryption Key للوضع الذي تمت فيه الدفعة مُدخل، وأن جدار حماية أو حماية بكلمة مرور لا يمنع العنوان. فعّل Logging وراجع حقل Log للاطلاع على webhooks المرفوضة.

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

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

يرد webhook بالرسالة Busy, retry later: كانت السلة تُعالج بعودة العميل في اللحظة نفسها، أو تعذّر إنشاء الطلب (مثلًا لأن الوحدة معطّلة). لم يتغير شيء، وستعيد Peach Payments إرسال webhook. ويوضح السجل السبب.

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

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

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

يرى العميل الرسالة The payment form is not available right now: Access Token أو Entity ID للوضع الحالي غير صحيح. تحقق من بيانات الاعتماد والوضع، واقرأ السجل للحصول على رمز Peach Payments.

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

عند الحفظ تظهر رسالة تفيد بأن مفتاح webhook يجب أن يكون المفتاح السداسي العشري المكوّن من 64 خانة: القيمة المُدخلة ليست المفتاح الصادر من Peach Payments. ولا يمكن فك تشفير webhooks حتى يُصحَّح.

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

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

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