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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

HTTPS: يجب أن يستخدم موقعك HTTPS، لأن نموذج البطاقة موجود في صفحة الدفع الخاصة بك.

حساب OpenPay: حساب OpenPay من المكسيك أو كولومبيا أو بيرو. تحتاج إلى Merchant ID الخاص به، والمفتاح الخاص (sk_...) والمفتاح العام (pk_...). لوحتا التحكم للبيئة التجريبية والإنتاج لهما Merchant ID ومفاتيح مختلفة، والإضافة تفصل بينهما.

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

تُكتب البطاقة في صفحة الدفع الخاصة بك، لكنها تُقرأ وتُرمَّز داخل المتصفح بواسطة openpay.js. حقول البطاقة ليس لها اسم ولا تُرسل إلى خادمك أبدًا. ولأن نموذج البطاقة موجود في صفحتك، فإن نطاق PCI DSS الخاص بك هو SAQ A-EP؛ استشر الجهة المعالِجة لديك.

التثبيت

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

2. انقر Activate.

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

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

5. اختر Account country وأدخل مفاتيح البيئة التجريبية والإنتاج (راجع الإعدادات).

6. مُوصى به: أضف عنوان الـ webhook في لوحة تحكم OpenPay (راجع الإعدادات).

7. فعّل Enable / Disable واحفظ. جرّب دفعة ببطاقات اختبار البيئة التجريبية لـ OpenPay، ثم ألغِ تحديد Sandbox mode لقبول المدفوعات الحقيقية.

الإعدادات

توجد جميع الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > OpenPay. وفوق الحقول تحذّرك الصفحة عندما تكون مفاتيح الوضع الحالي ناقصة (وعندها تُخفى طريقة الدفع في صفحة الدفع)، وعندما لا تُقبل عملة المتجر من دولة الحساب المختارة، وتعرض Sandbox mode is enabled — no real charges are made. طالما وضع البيئة التجريبية مفعّل. وفي قائمة طرق الدفع يُعرض OpenPay على أنه يحتاج إلى إعداد حتى يحتوي الوضع الحالي على المفاتيح الثلاثة، وتظهر شارة وضع الاختبار طالما وضع البيئة التجريبية مفعّل.

عند الحفظ يُتحقق من المفاتيح. يجب أن يحتوي Merchant ID على أحرف وأرقام فقط، ويجب أن يبدأ المفتاح الخاص بـ sk_ والمفتاح العام بـ pk_. لا تُحفظ القيمة غير الصالحة: تبقى القيمة السابقة ويظهر خطأ، مثل Sandbox: The private key must start with sk_. وإذا كانت طريقة الدفع مفعّلة لكن مفاتيح الوضع الحالي ناقصة، فسترى أيضًا رسالة تفيد بأن البوابة تبقى مخفية في صفحة الدفع.

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء في صفحة الدفع. الافتراضي: Credit or debit card (OpenPay).

Description: النص الذي يظهر فوق نموذج البطاقة في صفحة الدفع. الافتراضي: Pay securely with your credit or debit card. Your bank may ask you to confirm the payment (3D Secure).

حساب OpenPay

يوجد Merchant ID والمفتاح الخاص (sk_) والمفتاح العام (pk_) في لوحة تحكم OpenPay ضمن Settings (Configuración). يحتوي القسم على روابط إلى لوحتي البيئة التجريبية والإنتاج في المكسيك وكولومبيا وبيرو.

Account country: دولة حساب OpenPay الخاص بك. تحدد واجهة OpenPay البرمجية، ومكتبة openpay.js لتلك الدولة، والعملات المقبولة. الافتراضي: Mexico.

Sandbox mode: Use the OpenPay sandbox (test keys, no real charges) يحوّل المفاتيح والواجهة البرمجية معًا إلى البيئة التجريبية. تظهر شارة SANDBOX MODE عند الدفع طالما هو مفعّل. الافتراضي: مفعّل. ألغِ تحديده لقبول مدفوعات حقيقية.

Sandbox Merchant ID: الـ Merchant ID من لوحة البيئة التجريبية، Settings (Configuración)، مفاتيح API.

Sandbox Private Key: المفتاح الخاص للبيئة التجريبية. يبدأ بـ sk_. يُستخدم على الخادم فقط؛ لا تشاركه أبدًا.

Sandbox Public Key: المفتاح العام للبيئة التجريبية. يبدأ بـ pk_. يستخدمه openpay.js في المتصفح لترميز البطاقة.

Live Merchant ID: الـ Merchant ID من لوحة الإنتاج، Settings (Configuración)، مفاتيح API.

Live Private Key: المفتاح الخاص للإنتاج (sk_...).

Live Public Key: المفتاح العام للإنتاج (pk_...).

تُنقل المفاتيح من الإصدار 1.0 للإضافة (مجموعة مفاتيح واحدة وعلامة للبيئة التجريبية) تلقائيًا إلى حقول البيئة التجريبية أو الإنتاج.

Webhook

الـ webhook غير إلزامي، لكنه موصى به. يؤكد المدفوعات عندما لا يعود العميل من صفحة 3D Secure، مثلًا بعد إغلاق المتصفح. في لوحة تحكم OpenPay انتقل إلى Settings > Webhooks وأضف العنوان المعروض في هذا القسم من الإعدادات. يبدو هكذا: https://your-site/wc-api/webhook_wc_openpay/. انسخه تمامًا كما تعرضه الإعدادات. أضف الـ webhook في لوحة كل وضع تستخدمه (البيئة التجريبية والإنتاج).

عند إضافة الـ webhook يرسل OpenPay رمز تحقق إلى هذا العنوان. يظهر الرمز في هذا القسم مع تاريخ وصوله، حتى تتمكن من تأكيد الـ webhook في لوحة تحكم OpenPay.

اختر هذه الأحداث:

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

متقدم

Debug log: Log payment steps (errors are always logged) يكتب خطوات الدفع في WooCommerce > Status > Logs، بالمصدر wcp_openpay_gateway. تُسجَّل الأخطاء والتحذيرات حتى عند إيقافه. لا تُسجَّل المفاتيح ولا بيانات البطاقة ولا بيانات العميل أبدًا. الافتراضي: معطّل.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted. الافتراضي: معطّل.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Credit or debit card (OpenPay)) ويملأ Cardholder name وCard number وExpiry (MM/YY) وCard code (CVV). وعند تقديم الطلب يحوّل openpay.js البطاقة إلى رمز دفع لمرة واحدة في المتصفح، وتضيف مكتبة مكافحة الاحتيال الخاصة بـ OpenPay معرّف جلسة الجهاز. ولا يُرسَل إلى متجرك إلا هاتان القيمتان.

ثم تنشئ الإضافة عملية الخصم مع 3D Secure بإجمالي الطلب وبعملة الطلب، وترسل العميل إلى صفحة 3D Secure الخاصة ببنكه، والتي يقدمها OpenPay. تحصل كل محاولة على مرجع طلب خاص بها لدى OpenPay (رقم الطلب ولاحقة قصيرة). ووصف عملية الخصم هو Order # ورقم الطلب واسم موقعك. يُمرَّر اسم العميل وبريده الإلكتروني وهاتفه إلى OpenPay؛ ولا يُنشأ أي حساب عميل في OpenPay. يبقى الطلب في حالة في انتظار الدفع طالما العميل في صفحة 3D Secure.

عندما يعود العميل تقرأ الإضافة عملية الخصم من واجهة OpenPay البرمجية. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكده OpenPay: يجب أن تنتمي عملية الخصم إلى هذا الطلب، وأن تكون مكتملة، وأن يتطابق إجمالي الطلب وعملته تمامًا. وإذا لم تكن النتيجة معروفة بعد، تعرض صفحة استلام الطلب We are confirming your card payment with OpenPay. The order will be updated automatically — please do not pay again. ثم يحدّث الـ webhook الطلب.

إذا رُفضت البطاقة أو فشل 3D Secure يعود العميل إلى صفحة Pay for order مع الرسالة The card payment was not completed (declined or 3-D Secure failed). Please try again or use another card. ويمكنه الدفع مرة أخرى. وقبل أي محاولة جديدة تتحقق الإضافة من عملية الخصم السابقة للطلب: إذا كانت مدفوعة فعلًا يُعلَّم الطلب كمدفوع دون خصم ثانٍ؛ وإذا كانت لا تزال قيد المعالجة يرى العميل أن دفعة سابقة ما زالت تُعالج ولا ينبغي أن يدفع مجددًا؛ وإذا تعذّر التحقق من حالتها فلا تُجرى محاولة جديدة ويُطلب من العميل المحاولة بعد بضع دقائق.

تتلقى البطاقات المرفوضة رسالة واضحة، مثل The card has insufficient funds. Please use another card. أو The card has expired. Please use another card. أو The security code (CVV) is not valid. Please check it and try again. لا تُعرض أخطاء OpenPay التقنية على العملاء أبدًا؛ بل تذهب إلى ملاحظات الطلب والسجل.

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

تقبل الإضافة مدفوعات البطاقات فقط، مع تحصيل فوري. لا تتضمن البطاقات المحفوظة، ولا الاشتراكات، ولا الأقساط بدون فوائد (MSI) أو التقسيط، ولا الدفع بنقاط البطاقة، ولا الدفع نقدًا أو عبر SPEI أو PSE أو CoDi، ولا التفويض والتحصيل المنفصلان.

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

حالات الطلب

في انتظار الدفع: العميل في صفحة 3D Secure أو لم يُكمل الدفع. تعرض ملاحظة معرّف عملية الخصم.

قيد المعالجة: تم تأكيد الدفع. وهذه هي الحالة المعتادة في WooCommerce بعد الدفع؛ الطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط تصبح مكتملة. تعرض ملاحظة الطلب معرّف عملية الخصم والوضع (الإنتاج أو البيئة التجريبية). معرّف المعاملة هو معرّف عملية الخصم في OpenPay.

في الانتظار: عملية الخصم جارية ولم تُحصَّل بعد؛ أو أبلغ OpenPay عن عملية خصم مكتملة بمبلغ أو عملة مختلفين عن الطلب (لا يُعلَّم الطلب كمدفوع، وتعرض الملاحظة الفرق)؛ أو وصلت دفعة لطلب أُلغي من قبل. تحقّق من الطلب في لوحة تحكم OpenPay، ثم أكمله أو استرد الدفعة هناك.

فشل: رُفضت البطاقة عند إنشاء عملية الخصم، أو فشلت آخر محاولة أو أُلغيت أو انتهت صلاحيتها. يمكن للعميل الدفع مجددًا.

إذا وصلت عملية خصم ثانية مكتملة لطلب مدفوع بالفعل، فلا يتغير الطلب. وتطلب منك ملاحظة تبدأ بـ WARNING استرداد النسخة المكررة في لوحة تحكم OpenPay.

الاستردادات

للحسابات في المكسيك وبيرو: افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via Credit or debit card (OpenPay) (يعرض الزر عنوان طريقة الدفع الخاصة بك). الاسترداد الكامل والجزئي مدعومان. يُرسل الاسترداد بالوضع ودولة الحساب اللذين دُفع فيهما الطلب، لذلك أبقِ مفاتيح البيئة التجريبية مُدخَلة طالما بقيت طلبات تجريبية تحتاج إلى استرداد. وإذا لم يقبل OpenPay الاسترداد، تعرض WooCommerce الخطأ، مثل OpenPay refund failed: ...، ولا يُسجَّل أي استرداد. ويُضاف الاسترداد الناجح إلى ملاحظات الطلب مع معرّف استرداد OpenPay.

لا يدعم OpenPay Colombia استرداد البطاقات عبر الواجهة البرمجية، كما في الإضافات الرسمية لـ OpenPay. ولا يُعرض زر الاسترداد لكولومبيا؛ استرد عملية الخصم من لوحة تحكم OpenPay.

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

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

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

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

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

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

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

لا يظهر OpenPay في صفحة الدفع: تحقّق من أن الترخيص نشط، وأن Enable / Disable مفعّل، وأن الوضع الحالي يحتوي على المفاتيح الثلاثة: مفاتيح البيئة التجريبية في وضع البيئة التجريبية، ومفاتيح الإنتاج في وضع الإنتاج. وتحقّق من أن عملة المتجر مقبولة من Account country (المكسيك: MXN وUSD؛ كولومبيا: COP وUSD؛ بيرو: PEN وUSD). تعرض صفحة الإعدادات تحذيرًا في كل حالة من هذه الحالات.

تم الدفع لكن الطلب يبقى في حالة انتظار الدفع: لم يعد العميل من صفحة 3D Secure، والـ webhook لا يعمل. تحقّق من إضافة عنوان الـ webhook في لوحة تحكم OpenPay للوضع الذي تستخدمه، تمامًا كما تعرضه الإعدادات، مع الأحداث المذكورة أعلاه. وتحقّق من أن مفاتيح الوضع الذي دُفع فيه الطلب مُدخَلة: بدونها يرد الـ webhook بـ not configured، ويعيد OpenPay المحاولة لاحقًا.

يرد الـ webhook بـ ignored (unknown order): لم ينشئ هذا المتجر عملية الخصم لهذا الطلب، مثلًا عملية خصم لمتجر آخر على حساب OpenPay نفسه. لا يتغير شيء.

يرد الـ webhook بـ verification failed: تعذّر الوصول إلى واجهة OpenPay البرمجية لقراءة عملية الخصم. يعيد OpenPay المحاولة.

يرد الـ webhook بـ busy: كان الطلب يُحدَّث بواسطة طلب آخر في اللحظة نفسها. يعيد OpenPay المحاولة.

يرى العميل «The secure card form could not be loaded»: لم يُحمَّل openpay.js أو مكتبة مكافحة الاحتيال الخاصة بـ OpenPay في المتصفح، أو تعذّر إنشاء معرّف جلسة الجهاز. اطلب من العميل إعادة تحميل الصفحة والمحاولة مجددًا.

يرى العميل «The payment could not be processed right now»: رفض OpenPay الطلب أو لم يستجب. السبب موجود في ملاحظات الطلب وفي السجل، بالمصدر wcp_openpay_gateway. ومن الأسباب الشائعة Merchant ID أو مفتاح خاص غير صحيح. وإذا لم يستجب OpenPay، فتحقّق من عملية الخصم في لوحة تحكم OpenPay قبل أن يدفع العميل مرة أخرى.

«This test card cannot be used for real payments»: استُخدمت بطاقة اختبار من البيئة التجريبية بينما وضع البيئة التجريبية معطّل.

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

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

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

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

إلغاء تفعيل الإضافة يُبقي على جميع البيانات. ولإزالتها، ألغِ تفعيلها ثم احذفها من صفحة Plugins. يُحذف مفتاح الترخيص وحالة الترخيص لهذه الإضافة دائمًا. أما إعدادات البوابة، ورمز التحقق المحفوظ للـ webhook، وسجلات الإضافة فتُحذف فقط إذا كان Delete data on uninstall مفعّلًا، وإلا تبقى لإعادة التثبيت لاحقًا. وتُحفظ بيانات الطلبات دائمًا: تحتفظ الطلبات الحالية بملاحظات الدفع ومعرّفات المعاملات وبيانات الخصم اللازمة للاستردادات بعد إعادة التثبيت.

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