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

المتطلبات

WordPress: 6.0 أو أحدث.

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

PHP: 8.0 أو أحدث.

عملة المتجر: البيزو التشيلي (CLP). لا تحصّل Webpay Plus إلا بيزو صحيح، لذا اضبط Number of decimals على 0 في WooCommerce > Settings > General. وفي المتاجر ذات العملات الأخرى لا تظهر طريقة الدفع.

حساب Transbank: للمدفوعات الفعلية تحتاج إلى تجارة Webpay Plus قياسية (تحصيل فوري) مع Commerce Code الخاص بالإنتاج وAPI Key Secret. تمنحك Transbank الـ Commerce Code عند اعتماد انتسابك، والـ API Key Secret بعد عملية التحقق من التكامل (راجع توثيق المطورين لدى Transbank). للاختبارات لا تحتاج إلى بيانات اعتماد. رموز تجارة Webpay Plus Mall وOneclick والتحصيل المؤجل غير مدعومة.

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

التثبيت

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

2. انقر Activate.

3. اضبط عملة المتجر على البيزو التشيلي، وNumber of decimals على 0 في WooCommerce > Settings > General.

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

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

6. فعّل Enable / Disable وجرّب دفعة مع تفعيل Integration (test) mode، مستخدمًا بطاقات الاختبار الواردة في توثيق المطورين لدى Transbank.

7. للانتقال إلى الإنتاج، أدخل Production Commerce Code وProduction API Key Secret، وألغِ تحديد Integration (test) mode، ثم احفظ.

لا حاجة إلى إعداد عنوان إرجاع أو webhook في Transbank. تُرسل الإضافة عنوان الإرجاع الخاص بها مع كل معاملة.

الإعدادات

كل الإعدادات في صفحة واحدة: WooCommerce > Settings > Payments > Transbank Webpay Plus. فوق الحقول تحذّرك الصفحة عندما تكون بيئة الإنتاج مختارة لكن Production Commerce Code أو API Key مفقود أو غير صالح (فيُخفى Webpay عندها في صفحة الدفع)، وعندما لا تكون عملة المتجر CLP (فتُخفى طريقة الدفع)، وعندما تحتوي أسعار CLP على منازل عشرية (فتُقرَّب الإجماليات إلى بيزو صحيح). وما دام وضع التكامل مفعّلًا تعرض الصفحة Integration (test) environment: لا يُخصم أي مبلغ حقيقي. وبعد الحفظ تتبع التحذيرات الإعدادات الجديدة. وفي قائمة طرق الدفع، تُعلَّم البوابة على أنها تحتاج إلى إعداد عندما تكون بيئة الإنتاج مختارة دون بيانات اعتماد صالحة.

عام

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

Title: اسم طريقة الدفع الذي يراه العملاء عند الدفع. الافتراضي: Webpay Plus.

Description: النص الذي يظهر أسفل طريقة الدفع عند الدفع. الافتراضي: Pay with credit, debit or prepaid card via Webpay.

البيئة وبيانات الاعتماد

يحتوي نص هذا القسم على رابط إلى توثيق المطورين لدى Transbank، ويشرح متى تمنحك Transbank بيانات اعتماد الإنتاج.

Integration (test) mode: Use the Transbank integration environment. تُرسَل المدفوعات إلى بيئة التكامل لدى Transbank برمز التجارة العام للاختبار (597055555532)، ويُملأ تلقائيًا. لا تُستخدم بيانات اعتماد الإنتاج أدناه، ولا يُخصم أي مبلغ حقيقي. الافتراضي: مفعّل. ألغِ تحديده للانتقال إلى الإنتاج.

Production Commerce Code: رمز تجارة الإنتاج الخاص بك (Tbk-Api-Key-Id): 12 رقمًا، يبدأ بـ 5970. إذا كان رمزك 8 أرقام، فأدخله كما هو؛ تضيف الإضافة البادئة 5970 عند الحفظ. تُحذف المسافات والرموز الأخرى. رموز تجارة الاختبار العامة لدى Transbank غير مقبولة في الإنتاج.

Production API Key Secret: قيمة Tbk-Api-Key-Secret لتجارة الإنتاج لديك. احتفظ بها سرّية. تُحذف المسافات عند الحفظ.

متقدم

Debug log: Log API requests and returns (errors are always logged). تُكتب التفاصيل في WooCommerce > Status > Logs بالمصدر wcp_transbank_gateway؛ وللحقل رابط view logs. تُسجَّل الأخطاء والتحذيرات حتى لو كان هذا الخيار معطّلًا. لا تُسجَّل بيانات البطاقة ولا مفاتيح API ولا الرموز الكاملة. الافتراضي: معطّل.

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

الاختبار والإنتاج

Integration (test) mode يحدد وجهة المدفوعات الجديدة. كل دفعة تتذكر بيئتها: تأكيد الدفعة واستردادها يذهبان دائمًا إلى البيئة التي أُنشئت فيها (التكامل أو الإنتاج) وبيانات الاعتماد نفسها، حتى لو غيّرت الوضع لاحقًا.

الدفع

يختار العميل طريقة الدفع (افتراضيًا Webpay Plus) ويُتمّ الطلب. في وضع التكامل تعرض صفحة الدفع TEST MODE: Integration environment. لا توجد مبالغ حقيقية. تُنشئ الإضافة معاملة Transbank بإجمالي الطلب بالبيزو الصحيح (يُقرَّب الإجمالي الذي يحتوي على منازل عشرية إلى أقرب بيزو)، وتُرسل العميل إلى صفحة قصيرة Redirecting to Webpay. Please wait...، تنقله إلى نموذج Webpay. وبدون JavaScript ينقر العميل Proceed to Webpay. وفي Webpay يدفع العميل ببطاقة ائتمانية أو بطاقة خصم أو بطاقة مدفوعة مسبقًا.

عندما يعود العميل، تؤكد الإضافة المعاملة مع Transbank من خادم إلى خادم (commit). لا يُعلَّم الطلب كمدفوع إلا بعد تأكيد Transbank: يجب أن يكون الرد موافَقًا عليه، ويجب أن يطابق المبلغ ورقم الطلب (buy order) والجلسة ما أرسله المتجر لهذه المحاولة. ثم يرى العميل صفحة استلام الطلب. وإذا فشل طلب التأكيد، مثلًا بسبب انتهاء المهلة، تسأل الإضافة Transbank عن حالة المعاملة. وإذا بقيت الحالة غير معروفة، لا يتغير الطلب، ويرى العميل We could not confirm your Webpay payment with Transbank. Please try again in a moment; if your card was charged, contact us before paying again.

إذا ألغى العميل في Webpay، أو انتهت صلاحية نموذج Webpay أو أبلغ عن خطأ، فلا يُخصم أي مبلغ. يبقى الطلب في انتظار الدفع، ويعود العميل إلى صفحة Pay for order مع رسالة، مثل You cancelled the Webpay payment. Nothing was charged — you can try again or choose another payment method. وعند رفض البطاقة تظهر Your Webpay payment was rejected and nothing was charged. Please try again or choose another payment method. ويستطيع العميل الدفع مجددًا من الصفحة نفسها. وكل محاولة جديدة هي معاملة Webpay جديدة.

تُؤكَّد كل محاولة Webpay مرة واحدة على الأكثر. إعادة تحميل صفحة العودة، أو زر الرجوع في المتصفح، أو عودة ثانية في اللحظة نفسها، لا تؤكد أبدًا مرتين ولا تغيّر الطلب. وإذا لم يعد الطلب بحاجة إلى دفع (مدفوع بمحاولة أخرى، أو ملغى، أو مسترد)، فلا تُؤكَّد العودة المتأخرة، ولذلك لا تخصمها Transbank. ويرى العميل This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged.

إذا تعذّر على Webpay بدء الدفع، يرى العميل رسالة قصيرة، مثل Could not connect to Webpay. Please try again in a moment. أو Webpay payments are not available at the moment. Please choose another payment method. ويُكتب السبب التقني في السجل.

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

ليس لدى Transbank webhook للدفع: تُعالَج النتيجة عند عودة العميل من Webpay. وإذا أغلق العميل المتصفح في Webpay ولم يعد أبدًا، فلا تُؤكَّد المعاملة ويبقى الطلب معلّقًا؛ وبحسب Transbank لا تُسوَّى المعاملات غير المؤكدة. لا تدعم الإضافة Webpay Plus Mall أو البطاقات المحفوظة في Oneclick أو الاشتراكات أو التحصيل المؤجل أو تحويل العملات.

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

حالات الطلب

Pending payment: أُرسل العميل إلى Webpay ولم يدفع بعد، أو ألغى، أو ترك النموذج ينتهي، أو لم يمكن تأكيد الدفع بعد. تسجّل ملاحظة كل محاولة مغلقة مع رقم الطلب (buy order) الخاص بها.

Processing or Completed: وافقت Transbank على الدفع. تُحدَّد الحالة بواسطة WooCommerce: قيد التجهيز، أو مكتمل للطلبات التي تحتوي على منتجات افتراضية قابلة للتنزيل فقط. تعرض ملاحظة الطلب رمز التفويض، وآخر أربعة أرقام من البطاقة، ورقم الطلب (buy order)، والمبلغ، ونوع الدفع، وعدد الأقساط. ورقم المعاملة هو رمز Webpay.

On hold: فوّضت Transbank دفعة لا تطابق الطلب (المبلغ أو رقم الطلب أو معرّف الجلسة)، مثلًا لأن الطلب عُدّل بعد بدء الدفع. وتسرد الملاحظة الفروق. تحقّق من بوابة Transbank، ثم استرد الطلب أو أكمله.

Failed: رُفض الدفع. ولم يُخصم أي مبلغ. تعرض الملاحظة رمز الرد والحالة.

إذا أعاد Webpay دفعة لطلب مدفوع أو ملغى أو مسترد بالفعل، فلا تُؤكَّد الدفعة، وتطلب منك ملاحظة التحقق من بوابة Transbank إذا أبلغ العميل عن خصم. ولا تتأثر الطلبات الحالية بالمحاولات اللاحقة.

الاستردادات

يُعرض زر الاسترداد فقط للطلبات المدفوعة عبر Webpay. افتح الطلب، وانقر Refund، وأدخل المبلغ، ثم انقر Refund via Webpay Plus (يستخدم الزر عنوان طريقة الدفع). يُدعم الاسترداد الكامل والجزئي بالبيزو الصحيح. ويُرفض المبلغ الجزئي الذي يحتوي على منازل عشرية مع رسالة Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. وتُقرَّب بقية إجمالي الطلب الذي يحتوي على منازل عشرية بالطريقة نفسها التي يُقرَّب بها الخصم. ويذهب الاسترداد إلى البيئة التي تمّ فيها الدفع، لذلك يجب ضبط بيانات اعتماد الإنتاج في بيئة الإنتاج.

ترد Transbank بـ reversal (REVERSED) أو nullification (NULLIFIED). يُضاف الاسترداد الناجح إلى ملاحظات الطلب مع المبلغ والنوع ورمز التفويض والرصيد المتبقي لدى Transbank. وإذا لم تقبل Transbank الاسترداد، يعرض WooCommerce الخطأ ولا يُسجَّل أي استرداد. ولا تُستورَد الاستردادات التي تُجرى في بوابة Transbank إلى WooCommerce.

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

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

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

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

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

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

لا يظهر Webpay Plus في صفحة الدفع: تحقق من أن الترخيص فعّال، وأن Enable / Disable مفعّل، وأن عملة المتجر CLP (في صفحة Pay for order عملة الطلب)، وأنه عند إيقاف وضع التكامل تكون محفوظة قيمة صالحة لـ Production Commerce Code (12 رقمًا يبدأ بـ 5970) وProduction API Key Secret. تعرض صفحة الإعدادات تحذيرًا لكل شرط ناقص.

تمّ الدفع لكن الطلب ما زال Pending payment: ليس لدى Transbank webhook، لذلك لا يُؤكَّد الطلب إلا عندما يعود العميل من Webpay. وإذا أغلق العميل المتصفح في Webpay، فلم تُؤكَّد المعاملة، وبحسب Transbank لن تُسوَّى. تحقّق من ملاحظات الطلب والسجل والمعاملة في بوابة Transbank.

يرى العميل We could not confirm your Webpay payment with Transbank: فشل طلب التأكيد ولم يمكن التحقق من الحالة. لم يتغير الطلب، وأُضيفت ملاحظة. يمكن للعميل المحاولة مجددًا بعد لحظات. وإذا أظهرت بوابة Transbank المعاملة كمفوَّضة، فأكّدها هناك قبل الشحن.

يرى العميل خطأ عند إتمام الطلب: فعّل Debug log وراجع WooCommerce > Status > Logs، بالمصدر wcp_transbank_gateway. وعادةً تعني رسالة Webpay payments are not available at the moment وجود بيانات اعتماد إنتاج خاطئة. وتعني Could not connect to Webpay أنه تعذّر الوصول إلى Transbank. ولا يمكن دفع طلب بعملة غير CLP عبر Webpay.

الإجماليات والاستردادات تختلف ببضعة بيزو: أسعار CLP تحتوي على منازل عشرية. وWebpay يحصّل بيزو صحيحًا، لذلك تُقرَّب الإجماليات. اضبط Number of decimals على 0.

فشل الاسترداد برسالة The production Commerce Code / API Key are missing: تمّ الدفع في بيئة الإنتاج، وبيانات اعتماد الإنتاج غير محفوظة. أدخلها وأعد المحاولة.

فشل الاسترداد برسالة Transbank refused the refund أو Transbank did not approve the refund: لم تقبله Transbank؛ وتعرض الرسالة السبب أو النوع ورمز الرد الذي أعادته. ولم يُسترد أي مبلغ. تحقّق من المعاملة في بوابة Transbank.

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

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

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

Transbank وWebpay علامتان تجاريتان لمالكيهما. هذه الإضافة غير تابعة لـ Transbank ولا تحظى بتأييدها.