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

المتطلبات

WordPress: 6.2 أو أحدث.

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

PHP: 8.0 أو أحدث.

HTTPS: يجب أن تستخدم صفحة الدفع الخاصة بك HTTPS، كما هو مطلوب لقبول مدفوعات البطاقات (PCI DSS). تُرسَل بيانات البطاقة من متصفح العميل مباشرةً إلى Pin Payments عبر Pin.js ولا تصل إلى خادمك أبدًا، لذلك يخضع المتجر لمتطلبات PCI SAQ A-EP.

حساب Pin Payments: حساب تاجر لدى Pin Payments (للشركات في أستراليا أو نيوزيلندا؛ يستطيع العملاء الدفع من أي مكان). تحتاج إلى مفتاحه القابل للنشر (publishable key) ومفتاحه السري (secret key)، للإنتاج، ولأغراض الاختبار إلى مفاتيح بيئة الاختبار. لا حاجة إلى سر webhook: الإضافة لا تستخدم webhooks.

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

التثبيت

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

2. انقر على Activate.

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

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

5. في لوحة Pin Payments، افتح Account > API Keys، وانسخ مفاتيح الاختبار إلى Test publishable key وTest secret key. أبقِ Test mode مفعّلًا، وفعّل Enable/Disable، ثم احفظ.

6. أجرِ طلبًا تجريبيًا ببطاقة اختبار من Pin Payments. عندما يعمل كل شيء، أدخل مفاتيح الإنتاج، وألغِ تفعيل Test mode، ثم احفظ.

الإعداد

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

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

Title: عنوان طريقة الدفع الذي يظهر في صفحة الدفع. الافتراضي: Credit card (Pin Payments).

Description: وصف طريقة الدفع الذي يظهر في صفحة الدفع. الافتراضي: Pay with your credit card via Pin Payments.

مفاتيح API

تجد مفاتيحك في لوحة Pin Payments ضمن Account > API Keys. تعمل مفاتيح الاختبار مع واجهة الاختبار فقط، وتعمل مفاتيح الإنتاج مع واجهة الإنتاج فقط. يستخدم Pin.js المفتاح القابل للنشر في متصفح العميل. ولا يغادر المفتاح السري خادمك أبدًا.

Test mode: Enable test mode. يستخدم بيئة اختبار Pin Payments (test-api.pinpayments.com) ومفاتيح الاختبار. لا تُنفَّذ أي خصومات حقيقية، ويرى العملاء في نموذج البطاقة الرسالة وضع الاختبار — لن يتم تنفيذ أي خصم حقيقي.. وعند تعطيله تُستخدم واجهة الإنتاج (api.pinpayments.com) ومفاتيح الإنتاج. الافتراضي: مفعّل.

Test publishable key: المفتاح القابل للنشر لحساب الاختبار الخاص بك لدى Pin Payments.

Test secret key: المفتاح السري لحساب الاختبار الخاص بك لدى Pin Payments. وهو حقل كلمة مرور.

Live publishable key: المفتاح القابل للنشر لحساب الإنتاج الخاص بك لدى Pin Payments.

Live secret key: المفتاح السري لحساب الإنتاج الخاص بك لدى Pin Payments. وهو حقل كلمة مرور.

تُزال المسافات حول المفاتيح. ويجب ملء المفتاحين للوضع الحالي، وإلا فلن تظهر البوابة في صفحة الدفع.

متقدم

Debug log: Log Pin Payments API calls — تُحفظ السجلات في WooCommerce > Status > Logs ضمن المصدر wcp_pinpayments_gateway. تُسجَّل الأخطاء دائمًا؛ فعّل هذا الخيار لتسجيل كل استدعاء API أيضًا. لا تُسجَّل بيانات البطاقات ومفاتيح API والبيانات الشخصية للعملاء أبدًا. الافتراضي: معطّل.

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

صفحة الدفع

يختار العميل طريقة الدفع (افتراضيًا Credit card (Pin Payments)، مع أيقونات Visa وMastercard وAmerican Express)، ويملأ Card number وExpiry (MM / YY) وCVC وName on card في صفحة الدفع الخاصة بك. وقبل الإرسال، يتحقق نموذج البطاقة من طول رقم البطاقة، وشهر انتهاء الصلاحية وسنته، وخانة CVC المكوّنة من 3 أو 4 أرقام، والاسم.

عند تقديم الطلب، يُرسل Pin.js من المتصفح بيانات البطاقة وعنوان الفوترة مباشرةً إلى Pin Payments ويحصل على رمز بطاقة لمرة واحدة. ولا يُرسَل إلى خادمك سوى هذا الرمز. ثم ينشئ خادمك عملية خصم محصّلة بإجمالي الطلب بعملة الطلب، بالوصف <store name> - Order <number>. وترد Pin Payments في الطلب نفسه. لا يُعلَّم الطلب كمدفوع إلا بعد أن تُبلغ Pin Payments عن خصم ناجح، وفقط إذا كان المبلغ والعملة مطابقين تمامًا لمبلغ الطلب وعملته. ثم يصل العميل إلى صفحة استلام الطلب.

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

الرسائل التي قد يراها العميل: تم رفض بطاقتك. يُرجى استخدام بطاقة أخرى أو التواصل مع البنك.؛ ليس في بطاقتك رصيد كافٍ. يُرجى استخدام بطاقة أخرى.؛ انتهت صلاحية بطاقتك. يُرجى استخدام بطاقة أخرى.؛ رمز أمان البطاقة (CVC) غير صحيح.؛ نوع البطاقة هذا غير مقبول. يُرجى استخدام Visa أو Mastercard أو American Express.؛ فشل الدفع: مع سبب من Pin Payments للبيانات المرفوضة؛ انتهت صلاحية بيانات بطاقتك. يُرجى إدخالها مرة أخرى وإعادة المحاولة. عندما لا يمكن استخدام الرمز؛ تعذّر تحميل نموذج البطاقة الآمن. يُرجى إعادة تحميل الصفحة أو اختيار طريقة دفع أخرى. عندما لا يُحمَّل Pin.js؛ مدفوعات البطاقات غير متاحة مؤقتًا. يُرجى المحاولة لاحقًا أو اختيار طريقة دفع أخرى. عندما ترفض Pin Payments المفتاح السري؛ لم نتمكن من تأكيد دفعتك لدى Pin Payments. يُرجى التحقق من بريدك الإلكتروني وكشف حسابك للبطاقة قبل المحاولة مرة أخرى، أو التواصل معنا. عندما لا ترد Pin Payments. وتُسجَّل التفاصيل الفنية في ملاحظات الطلب وفي السجل.

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

لا تتضمن الإضافة مسار 3-D Secure. فإذا كان حسابك لدى Pin Payments يتطلب 3-D Secure، تبقى عملية الخصم معلقة وتُفشل الإضافة الطلب، فلا تُخصم أي أموال في تلك المحاولة؛ ويرى العميل الرسالة تعذّر إكمال الدفع بالبطاقة (مطلوب تحقق إضافي). يُرجى تجربة بطاقة أخرى أو طريقة دفع أخرى. ولا يوجد وضع التفويض فقط مع تحصيل لاحق، ولا بطاقات محفوظة، ولا WooCommerce Subscriptions، ولا Apple Pay أو Google Pay، ولا webhooks.

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

Order statuses

Processing: أبلغت Pin Payments عن خصم ناجح ومحصّل بالمبلغ والعملة الدقيقين للطلب. تنتقل الطلبات التي تحتوي على منتجات رقمية قابلة للتنزيل فقط إلى الحالة مكتمل، وهي الافتراضية في WooCommerce. وتعرض ملاحظة الطلب المبلغ ورمز الخصم (وTEST MODE للمدفوعات التجريبية). ومعرّف المعاملة هو رمز الخصم لدى Pin Payments.

Failed: رُفضت البطاقة، أو بقي الخصم معلقًا (3-D Secure)، أو رفضت Pin Payments المفتاح السري أو الطلب. وتضيف كل محاولة فاشلة ملاحظةً إلى الطلب تتضمن رمز الخطأ ورسالة Pin Payments، حتى إن كان الطلب في حالة فاشل من محاولة سابقة. ويمكن للعميل إعادة المحاولة بالطلب نفسه.

Pending payment: لم تُقدّم Pin Payments ردًا واضحًا (انتهاء مهلة، أو خطأ في الخادم، أو رد غير قابل للقراءة). لا يُعلَّم الطلب كفاشل، لأن الخصم ربما يكون قد أُنشئ. وتطلب منك الملاحظة البحث عن وصف الخصم في لوحة Pin Payments قبل أن يدفع العميل مرة أخرى أو قبل شحن الطلب. وهذه الحالة هي قيد انتظار الدفع.

On hold: خصمت Pin Payments مبلغًا أو عملةً تختلف عن الطلب (تعرض الملاحظة المبلغ المتوقع والمبلغ المخصوم)، أو أن الخصم مُعتمَد لكنه غير محصّل. تحقّق من الخصم في لوحة Pin Payments قبل تنفيذ الطلب.

الاستردادات

افتح الطلب، وانقر على Refund، وأدخل المبلغ، ثم انقر على Refund via Credit card (Pin Payments) (يعرض الزر Title الخاص بك). يُدعم الاسترداد الكامل والجزئي. ويُرسَل الاسترداد إلى البيئة (الاختبار أو الإنتاج) التي دُفع فيها الطلب، لذلك يجب ضبط المفتاح السري لذلك الوضع. ويضيف الطلب الناجح ملاحظةً إلى الطلب تتضمن المبلغ ورمز الاسترداد لدى Pin Payments وحالته. وتعالج Pin Payments الاستردادات بشكل غير متزامن، لذلك تكون الحالة عادةً Pending. وإذا رفضت Pin Payments الاسترداد أو لم ترد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد.

لا تتم مزامنة الاستردادات التي تُجرى في لوحة Pin Payments مع WooCommerce، لذلك أجرِها من WooCommerce.

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

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

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

من دون مفتاح فعّال، لا تظهر Pin Payments للعملاء في صفحة الدفع. وإذا بدأ الدفع رغم ذلك، يرى العميل الرسالة طريقة الدفع هذه غير متاحة. يُرجى اختيار طريقة أخرى. ويستمر مديرو المتجر المسجّلو الدخول في رؤية طريقة الدفع، مع الوسم (بدون ترخيص — مرئية للمسؤولين فقط)، حتى تتمكن من إعداد الإضافة واختبارها قبل شراء المفتاح. ويظهر تذكير في صفحة الإضافات وفي صفحات WooCommerce. ولا تتأثر الطلبات الحالية: تظل الاستردادات تعمل.

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

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

لا تظهر Pin Payments في صفحة الدفع: تحقّق من أن الترخيص فعّال، وأن Enable/Disable مفعّل، وأن المفتاحين للوضع الحالي مملوءان (Test publishable key وTest secret key في وضع الاختبار، وإلا فمفاتيح الإنتاج)، وأن عملة السلة واحدة من العملات الـ14 المدعومة. وفي صفحة Pay for order، تُعتمد عملة الطلب. وتعرض صفحة الإعدادات خطأً عند غياب المفاتيح وعند عملة غير مدعومة.

تعرض صفحة الدفع "لم نتمكن من تأكيد دفعتك": لم ترد Pin Payments في الوقت المناسب. يبقى الطلب في حالة قيد انتظار الدفع مع ملاحظة. ابحث في لوحة Pin Payments عن خصم بالوصف <store name> - Order <number> قبل أن يدفع العميل مرة أخرى أو قبل شحن الطلب. ولا تبحث الإضافة عن هذا الخصم تلقائيًا، وأي محاولة جديدة تُنشئ خصمًا جديدًا.

يرى العملاء "مدفوعات البطاقات غير متاحة مؤقتًا": رفضت Pin Payments المفتاح السري. وتطلب ملاحظة الطلب التحقق من مفاتيح الوضع الحالي. وتعمل مفاتيح الاختبار في وضع الاختبار فقط، وتعمل مفاتيح الإنتاج في وضع الإنتاج فقط.

تفشل الطلبات مع الرسالة "مطلوب تحقق إضافي": يتطلب حسابك لدى Pin Payments تفعيل 3-D Secure، وهو غير مدعوم في الإضافة. اطلب من Pin Payments إيقاف 3-D Secure الإلزامي.

طلب في حالة On hold مع ملاحظة "does not match": أبلغت Pin Payments عن مبلغ أو عملة للخصم تختلف عن الطلب. تحقّق من الخصم في لوحة Pin Payments، ثم استرد المبلغ يدويًا أو أكمل الطلب يدويًا.

تعذّر تحميل نموذج البطاقة الآمن: لم يُحمَّل Pin.js من شبكة Pin Payments في المتصفح، مثلًا بسبب مانع السكربتات أو إضافة تخزين مؤقت أو تحسين تعدّل السكربتات. استثنِ صفحة الدفع من هذه التحسينات.

يفشل الاسترداد: اقرأ الرسالة. تعني الرسالة المتعلقة بالوضع TEST أو LIVE أن المفتاح السري للوضع الذي دُفع فيه الطلب فارغ. وتعني Pin Payments did not confirm the refund أنه لم يصل أي رد؛ تحقّق من الخصم في لوحة Pin Payments قبل إعادة المحاولة.

فشل الدفع بسبب من Pin Payments: رفضت Pin Payments تفاصيل الخصم، مثلًا مبلغًا أقل من الحد الأدنى للخصم في تلك العملة. يرى العميل السبب، وتتضمن ملاحظة الطلب رمز الخطأ.

المدفوعات التجريبية: يستخدم وضع الاختبار بيئة الاختبار ومفاتيح الاختبار. استخدم بطاقات الاختبار من وثائق المطورين لدى Pin Payments، مثلًا 4200 0000 0000 0000 (ناجحة) أو 4100 0000 0000 0001 (مرفوضة)، مع أي تاريخ انتهاء مستقبلي وأي رمز CVC. تحتفظ الطلبات بالوضع الذي دُفعت فيه، لذلك تذهب الاستردادات إلى البيئة الصحيحة بعد تغيير الوضع.

مكان العثور على الأخطاء: تُكتب الأخطاء دائمًا في WooCommerce > Status > Logs ضمن المصدر wcp_pinpayments_gateway. فعّل Debug log لرؤية كل استدعاء API.

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

للمطورين: يغيّر الفلتر wc_ppg_supported_currencies قائمة العملات، ويغيّر الفلتر wc_ppg_icon الأيقونة في قائمة طرق الدفع في WooCommerce.

الإزالة

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

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