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

المتطلبات

OpenCart: الإصدار 3.0.x (تم الاختبار على الإصدار 3.0.5.0) أو 4.0.2 أو أحدث (تم الاختبار على 4.1.0.3).

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

العملة: البيزو التشيلي (CLP). أضفها في System > Localisation > Currencies إذا لم تكن موجودة في متجرك، مع 0 منازل عشرية: تحصّل Webpay Plus مبالغ بالبيزو الصحيح فقط. بالنسبة للطلبات بعملة أخرى لا تظهر طريقة الدفع.

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

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

التثبيت

التنزيل ملف zip واحد يحتوي على الحزم الخاصة بالإصدارين من OpenCart. فُكّ ضغطه على حاسوبك. ويحتوي على README.txt، وحزمة OpenCart 3 wcp_transbank_gateway-oc3-(version).ocmod.zip، وحزمة OpenCart 4 wcp_transbank_gateway.ocmod.zip. ثبّت الحزمة الخاصة بإصدار OpenCart لديك فقط. مفتاح الترخيص واحد للإصدارين.

OpenCart 3

1. في لوحة الإدارة انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف wcp_transbank_gateway-oc3-(version).ocmod.zip. لا تحتوي الإضافة على تعديلات OCMOD، لذلك لا تحتاج Extensions > Modifications إلى تحديث. وبدلاً من أداة التثبيت يمكنك أيضاً نسخ محتويات المجلد upload من هذه الحزمة إلى المجلد الجذر لمتجرك.

2. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Transbank Gateway وانقر على Install (زر + الأخضر). يحتاج مستخدم الإدارة لديك إلى صلاحية تعديل قائمة إضافات الدفع.

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

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

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

OpenCart 4

1. في لوحة الإدارة انتقل إلى Extensions > Installer، وانقر على Upload، ثم اختر الملف wcp_transbank_gateway.ocmod.zip. لا تُغيّر اسم الملف: يأخذ OpenCart 4 رمز الإضافة من اسم الملف، ولا تعمل الحزمة إذا أُعيدت تسميتها.

2. تظهر الحزمة في قائمة الإضافات المثبتة في الصفحة نفسها. انقر على Install (زر + الأخضر) بجانبها.

3. انتقل إلى Extensions > Extensions واختر النوع Payments. ابحث عن VibeFox Transbank Gateway، وانقر على Install (زر + الأخضر)، ثم على Edit (زر القلم).

4. أدخل مفتاح الترخيص والإعدادات كما في الخطوات من 3 إلى 5 لـ OpenCart 3. صفحة الإعدادات وحقولها متطابقة في الإصدارين. الرابط الوحيد المختلف هو عنوان إعادة التوجيه (انظر عنوان إعادة التوجيه).

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

الإعدادات

جميع الإعدادات موجودة في صفحة الإضافة: Extensions > Extensions > Payments > VibeFox Transbank Gateway > Edit. تظهر الأقسام في القائمة على اليسار؛ وزر Save أسفل القائمة يحفظ الصفحة كاملة. فوق الإعدادات تنبّهك الصفحة عندما تكون بيئة الإنتاج محددة لكن Commerce Code أو API Key الخاص بالإنتاج مفقود أو غير صالح (وعندئذٍ يُخفى Webpay عند الدفع)، وعندما تكون العملة الافتراضية للمتجر غير CLP (تُخفى طريقة الدفع للعملات الأخرى)، وعندما يحتوي CLP على منازل عشرية (تُقرّب الإجماليات إلى بيزو صحيح). وما دام وضع التكامل مفعّلاً، تبيّن الصفحة أن المدفوعات تُرسل إلى بيئة تكامل Transbank بكود التاجر العام للاختبار، وأنه لا يتم خصم أي مبلغ حقيقي. من دون صلاحية تعديل الإضافة تعرض الصفحة الإعدادات لكنها لا تستطيع حفظها.

عند الحفظ، لا يمكن أن يكون Title فارغاً أو أطول من 128 حرفاً، ويجب أن يكون Sort Order عدداً صحيحاً (القيم السالبة مسموحة)، ويجب أن يكون Total رقماً أكبر من 0 أو يساويه، وأن تكون حالات الطلب موجودة؛ وإلا فلن يُحفظ أي شيء وتعرض الصفحة الخطأ.

Transbank Webpay Plus

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

Title: اسم طريقة الدفع الذي يراه العميل عند الدفع. وهو أيضاً الاسم المحفوظ لطريقة الدفع في الطلب. الافتراضي: Webpay Plus. حقل مطلوب، بحد أقصى 128 حرفاً.

Description: النص الذي يراه العميل في خطوة Confirm Order فوق زر التأكيد. الافتراضي: Pay with credit, debit or prepaid card via Webpay.

Sort Order: ترتيب Webpay بين طرق الدفع عند الدفع. اتركه فارغاً أو أدخل عدداً صحيحاً (القيم السالبة مسموحة).

Geo Zone: اعرض Webpay فقط لعناوين الدفع الواقعة ضمن المنطقة الجغرافية المحددة. الافتراضي: All zones. تُضبط المناطق الجغرافية في System > Localisation > Geo Zones.

Total: إجمالي الدفع، بالعملة الافتراضية للمتجر، الذي يجب أن يصل إليه الطلب قبل عرض Webpay. اتركه فارغاً لعرض Webpay لأي إجمالي.

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

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

Integration (test) mode: تُرسل المدفوعات إلى بيئة تكامل Transbank بكود التاجر العام للاختبار (597055555532)، ويُستخدم تلقائياً. لا تُستخدم بيانات اعتماد الإنتاج أدناه، ولا يُخصم أي مبلغ حقيقي. الافتراضي: on. ألغِ تفعيله للانتقال إلى الإنتاج. وما دام مفعّلاً يرى العملاء في خطوة Confirm Order الرسالة TEST MODE — بيئة التكامل. لا توجد رسوم حقيقية.

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

Production API Key Secret: الـ Tbk-Api-Key-Secret الخاص بتاجر الإنتاج لديك. احتفظ به سرياً. تُحذف المسافات عند الحفظ. لا يُعرض المفتاح المحفوظ مرة أخرى: يبقى الحقل فارغاً ويعرض Saved — leave empty to keep it. أدخل قيمة جديدة فقط إذا أردت تغييره. ولحذف المفتاح المحفوظ، ضع علامة على Clear saved API key وانقر على Save.

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

عنوان إعادة التوجيه

Return from Webpay: العنوان الذي ترسل إليه Transbank العميل مجدداً، ويُعرض للمرجعية. في OpenCart 3 يبدو هكذا: https://your-store/index.php?route=extension/payment/wcp_transbank_gateway/back، وفي OpenCart 4 يبدو هكذا: https://your-store/index.php?route=extension/wcp_transbank_gateway/payment/wcp_transbank_gateway.back. لا يحتاج الأمر إلى أي إعداد لدى Transbank: الإضافة ترسل هذا العنوان مع كل معاملة (ليس لدى Transbank webhook: يُؤكَّد الدفع عندما يعود العميل). يجب أن يكون متاحاً من الإنترنت؛ ووضع الصيانة لا يحجبه (في OpenCart 4 تضيف الإضافة إجراء بدء التشغيل (startup action) لهذا الغرض).

الطلبات

ينشئ OpenCart الطلب في خطوة Confirm Order بدون حالة (طلب مفقود). لا يحصل الطلب على حالة إلا بعد أن يؤكد المتجر المعاملة مع Transbank (commit) عندما يعود العميل من Webpay. يسرد كل حقل أدناه حالات طلبات OpenCart الخاصة بك.

Order Status After Payment: الحالة التي تُعيَّن بعد دفعة Webpay معتمدة ومتحقق منها. الافتراضي: Processing.

Transbank Payment On Hold Status: وافقت Transbank على دفعة لا تطابق الطلب (المبلغ، أو buy order، أو session id): يُحتجز الطلب للمراجعة اليدوية، وتشرح ملاحظة السبب. الافتراضي: Pending، لأن OpenCart لا يملك حالة On hold. يمكنك إنشاء حالتك الخاصة في System > Localisation > Order Statuses واختيارها هنا.

Refunded Status: تُعيَّن عند استرداد الدفعة بالكامل من صفحة الطلب. الافتراضي: Refunded.

متقدم

Debug log: يسجّل طلبات API والردود في wc_tbk_debug.log.php داخل مجلد سجلات OpenCart (storage/logs). لا يمكن فتح الملف من الويب. تُسجَّل الأخطاء دائماً حتى عندما يكون هذا الخيار معطلاً. لا تُسجَّل بيانات البطاقات ولا مفاتيح API ولا الرموز الكاملة. الافتراضي: off.

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

Delete data on uninstall: عند التفعيل، يؤدي إلغاء تثبيت الإضافة إلى حذف إعدادات البوابة والسجل. تبقى بيانات الطلبات والمدفوعات محفوظة دائماً. الافتراضي: off.

الاستيراد / التصدير

Export: Download JSON يحفظ الإعدادات في ملف JSON. لا يتم تصدير API Key Secret.

Import: الصق ملف JSON المُصدَّر سابقاً وانقر على Import لاستعادة الإعدادات. يُحتفظ بمفتاح API المحفوظ.

الدفع

في خطوة Payment Method يختار العميل طريقة الدفع (افتراضياً Webpay Plus). وفي خطوة Confirm Order يرى العميل وصفك والملاحظة You will be redirected to Webpay (Transbank) to complete the payment. ينشئ OpenCart الطلب في هذه الخطوة، ما زال بلا حالة. عندما ينقر العميل على Confirm Order، تنشئ الإضافة معاملة Transbank بإجمالي الطلب بالبيزو الصحيح (يُقرَّب الإجمالي الذي يحتوي على كسور إلى أقرب بيزو)، وينتقل العميل مباشرةً إلى نموذج Webpay، حيث يدفع ببطاقة ائتمان أو بطاقة خصم أو بطاقة مدفوعة مسبقاً. في OpenCart 4 يختار العميل طريقة الدفع بزر Choose في كتلة طريقة الدفع، في النافذة Payment method options، وينقر على Confirm Order في أسفل صفحة الدفع.

عندما يعود العميل، تؤكد الإضافة (commit) المعاملة مع Transbank من الخادم إلى الخادم. لا يُعلَّم الطلب كمدفوع إلا بعد أن تؤكد Transbank ذلك: يجب أن يكون الرد معتمداً، ويجب أن يتطابق المبلغ وbuy order والجلسة مع ما أرسله المتجر لهذه المحاولة. ثم يحصل الطلب على حالته بالطريقة المعتادة في OpenCart، مع رسائل البريد الإلكتروني المعتادة للطلب وتحديث المخزون، ويرى العميل صفحة نجاح الطلب في OpenCart مع الرسالة Your Webpay payment has been received. وبالنسبة لطلب قيد المراجعة تعرض الصفحة Your Webpay payment was received and is being reviewed by the store.

إذا فشل استدعاء التأكيد، مثلاً بسبب انتهاء المهلة، تسأل الإضافة 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. وإذا كان طلب آخر يؤكد السلة نفسها في تلك اللحظة، أو وافقت Transbank على الدفع لكن لم تُعيَّن حالة الطلب بعد، فسيرى العميل صفحة Payment confirmation مكتوباً فيها Your Webpay payment is being confirmed. Please do not pay again — check again in a moment. مع الزرين Check again وBack to checkout. تُعيَّن الحالة بعدها من الرد المحفوظ دون تأكيد ثانٍ.

إذا ألغى العميل الدفع في Webpay، أو انتهت صلاحية نموذج Webpay أو أبلغ عن خطأ، فلا يُخصم أي مبلغ. يعود العميل إلى صفحة الدفع برسالة، مثل 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 جديدة. في OpenCart 4 تظهر هذه الرسائل فوق صفحة الدفع.

ينشئ OpenCart 3 طلباً جديداً في كل مرة تُعرض فيها خطوة Confirm Order. أما OpenCart 4 فيُبقي طلباً واحداً للدفع ويحدّثه، لذلك يدفع العميل بعد دفعة ملغاة أو مرفوضة الطلبَ نفسه بمعاملة Webpay جديدة. إذا تغير الطلب بعد بدء الدفع (لم تعد عملته أو إجماليه يطابقان المعاملة)، فلا تُؤكَّد المعاملة، لذلك لا تخصمها Transbank، ويرى العميل الرسالة Your order changed after the Webpay payment was started. The payment was not confirmed, so it was not charged — please pay again. وإذا كان للطلب حالة بالفعل، أو إذا كان طلب آخر من السلة نفسها مدفوعاً بالفعل، فإن الرجوع المتأخر لا يُؤكَّد أيضاً: ينتقل العميل إلى صفحة نجاح الطلب المدفوع، أو يرى This order can no longer be paid (it was cancelled or already paid). Your Webpay payment was not confirmed, so it was not charged.

في OpenCart 4، إذا حصل طلب الدفع على حالة دون دفعة Webpay أو أُغلق من المتجر في الأثناء، يُعاد العميل عند النقر التالي على Confirm Order إلى صفحة الدفع مع الرسالة نفسها، وتُدفع السلة بطلب جديد. وإذا كان طلب الدفع مدفوعاً بالفعل لكن السلة تغيّرت بعد ذلك، بما في ذلك كمية جديدة، يُعاد العميل إلى صفحة الدفع وتُدفع السلة الجديدة بطلب جديد.

إذا لم تتمكن Webpay من بدء الدفع، يبقى العميل في خطوة Confirm Order مع رسالة قصيرة، مثل Could not connect to Webpay. Please try again in a moment. أو Webpay could not start the payment. Please try again or choose another payment method. ويُكتب السبب التقني في السجل.

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

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

حالات الطلب

بلا حالة (طلب مفقود): أُرسل العميل إلى Webpay ولم يدفع، أو ألغى، أو ترك النموذج ينتهي، أو رُفضت البطاقة، أو لم يمكن تأكيد الدفع بعد. في Sales > Orders لا تظهر هذه الطلبات إلا مع الفلتر Order Status المضبوط على Missing Orders.

Order Status After Payment (الافتراضي Processing): وافقت Transbank على الدفع. تعرض ملاحظة رمز التفويض، وآخر أربعة أرقام من البطاقة، وbuy order، والمبلغ، ونوع الدفع، وعدد الأقساط.

Transbank Payment On Hold Status (الافتراضي Pending): وافقت Transbank على دفعة لا تطابق الطلب (المبلغ أو buy order أو الجلسة). تسرد الملاحظة الفروق. تحقق من بوابة Transbank ثم أتمم الطلب أو استرد الدفعة.

Refunded Status (الافتراضي Refunded): تم استرداد الدفعة بالكامل عبر الإضافة.

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

علامة تبويب VibeFox Transbank Gateway

في Sales > Orders افتح طلباً مدفوعاً عبر Webpay. في أسفل صفحة الطلب، بجوار History وAdditional، تعرض علامة التبويب VibeFox Transbank Gateway الـ Buy order وبيئته (تسمية Integration لمدفوعات الاختبار)، وStatus الدفعة، وAuthorization code، وCard / payment type مع عدد الأقساط، وCharged / refunded، ونموذج الاسترداد، وسجل الاستردادات، وWebpay attempts of the order، وTransbank notes. تظهر علامة التبويب للمستخدمين الذين لديهم صلاحية الوصول إلى الإضافة.

الاستردادات

في علامة التبويب أدخل Amount بالعملة CLP (تُملأ القيمة التي لم تُسترد بعد)، وأضف اختيارياً Reason (optional)، ثم انقر على Refund via Transbank. أكّد السؤال Refund this amount via Transbank? الاستردادات الكاملة والجزئية مدعومة بالبيزو الصحيح. تحتاج إلى صلاحية تعديل الإضافة (تُضبط في System > Users > User Groups). يُرفض المبلغ الجزئي الذي يحتوي على كسور مع الرسالة Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. ويُقرَّب الباقي الأخير من إجمالي طلب فيه كسور بالطريقة نفسها التي يُقرَّب بها الخصم. تُنفَّذ الاستردادات حتى مبلغ خصمته Transbank. يذهب الاسترداد إلى البيئة التي تمت فيها الدفعة، لذلك يجب ضبط بيانات اعتماد الإنتاج لدفعة الإنتاج.

ترد Transbank بعكس (REVERSED) أو إبطال (NULLIFIED). يُضاف الاسترداد الناجح إلى سجل الاستردادات والملاحظات مع المبلغ والنوع ورمز التفويض والرصيد المتبقي لدى Transbank. يضبط الاسترداد الكامل Refunded Status دون إشعار العميل ودون إعادة المنتجات إلى المخزون، مثل تغيير الحالة يدوياً. لا يغيّر الاسترداد الجزئي الحالة. إذا لم تقبل Transbank الاسترداد، تعرض علامة التبويب الخطأ ولا يُسجَّل أي استرداد.

لا ترجع مرتجعات المنتجات في Sales > Returns أي أموال عبر Transbank. الاستردادات التي تتم في بوابة Transbank لا تُستورد إلى OpenCart.

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

تعمل الإضافة بمفتاح ترخيص VibeFox من vibefox.net. كتلة الترخيص License — VibeFox Transbank Gateway هي الكتلة الأولى في Extensions > Extensions > Payments > VibeFox Transbank Gateway > Edit، فوق الإعدادات. الصق المفتاح في License key وانقر على Activate. بعد ذلك تعرض الكتلة المفتاح مخفياً جزئياً، والحالة (مثلاً تاريخ انتهاء صلاحية الترخيص ونطاقك)، والأزرار Check now لإعادة التحقق من الحالة، وChange key لإدخال مفتاح آخر، وRemove key لإزالة المفتاح من هذا المتجر. وأسفلها سطر Product: opencart-payment-transbank ورابط Manage licenses and domains in your account الذي يفتح حسابك على vibefox.net. لا يمكن تغيير المفتاح إلا لمستخدمي الإدارة الذين لديهم صلاحية Modify للإضافة. تتبع نصوص الكتلة لغة لوحة الإدارة (وتشمل الإنجليزية والروسية).

إذا لم يُقبل المفتاح، تبيّن الكتلة السبب، مثل Key not found أو This key belongs to another product أو Domain limit reached أو License expired on مع تاريخ. بعد تغيير عنوان المتجر، أو بعد تحرير خانة نطاق في حسابك، انقر على Check now. إذا تعذّر الوصول إلى خادم التراخيص، تواصل الإضافة العمل بآخر حالة معروفة.

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

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

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

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

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

تمت عملية الدفع لكن الطلب بقي بلا حالة: ليس لدى Transbank webhook، لذلك لا يحصل الطلب على حالته إلا عندما يعود العميل من Webpay. إذا أغلق العميل المتصفح في Webpay، فلم تُؤكَّد المعاملة، وبحسب Transbank لا تُسوَّى. فعّل Debug log، وراجع حقل Log، وتحقق من المعاملة في بوابة Transbank.

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

يرى العميل Your order changed after the Webpay payment was started: كان إجمالي الطلب أو عملته مختلفين عن المعاملة. لم يُخصم شيء؛ يدفع العميل مجدداً.

يرى العميل خطأً بعد Confirm Order: فعّل Debug log وراجع حقل Log في صفحة الإضافة. تعني Webpay payments are not available at the moment عادةً أن بيانات اعتماد الإنتاج غير صحيحة. وتعني Could not connect to Webpay أنه تعذّر الوصول إلى Transbank. وتعني Transbank Webpay only supports payments in CLP (Chilean Peso) أن الطلب بعملة أخرى. وتعني This payment method is not available. Please reload the checkout page. أن جلسة الدفع لم تعد تطابق الطلب: يعيد العميل تحميل صفحة الدفع.

الإجماليات والاستردادات تختلف ببضعة بيزوهات: عملة CLP لها منازل عشرية. تحصّل Webpay بيزوهات صحيحة، لذلك تُقرَّب الإجماليات. اضبط المنازل العشرية لـ CLP على 0 في System > Localisation > Currencies.

الطلب في حالة المراجعة بعد الدفع: اقرأ الملاحظات في علامة التبويب VibeFox Transbank Gateway (راجع حالات الطلب)، ثم أتمم الطلب أو استرد الدفعة.

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

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

يفشل الاسترداد برسالة Another request is processing this order: كان الطلب يُسترد أو يُؤكَّد في اللحظة نفسها. حاول مجدداً بعد لحظات.

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

انتقل إلى Extensions > Extensions، واختر النوع Payments، ثم انقر على Uninstall (الزر الأحمر −) بجوار VibeFox Transbank Gateway. يُحذف دائماً مفتاح الترخيص وحالة الترخيص لهذه الإضافة. تحذف OpenCart دائماً إعدادات الإضافة الخاصة بها: Enable / Disable وSort Order وGeo Zone وTotal وحالات الطلبات في قسم Orders، وهذه تعود إلى قيمها الافتراضية عند إعادة التثبيت. كما يُحذف حدث OpenCart الخاص بالإضافة (في OpenCart 4 أحداثها وإجراء بدء التشغيل الخاص بها، الذي يسمح بمرور العودة من Webpay في وضع الصيانة). إذا كان Delete data on uninstall مفعّلاً، تُحذف بقية إعدادات البوابة (العنوان، والوصف، ووضع التكامل، وبيانات الاعتماد، ومفتاح سجل التصحيح) والسجل. إذا كان معطلاً، فتُحفظ لإعادة التثبيت لاحقاً. تُحفظ دائماً محاولات Webpay واستردادات الطلبات، لذلك يمكن استرداد الطلبات المدفوعة سابقاً بعد إعادة التثبيت. تحتفظ الطلبات الموجودة بملاحظات الدفع الخاصة بها.

في OpenCart 4، لحذف ملفات الإضافة أيضاً، انتقل إلى Extensions > Installer بعد إلغاء التثبيت، وانقر على Uninstall (الزر البرتقالي −) بجوار VibeFox Transbank Gateway في قائمة الإضافات المثبتة، ثم على Delete (زر سلة المهملات الأحمر) لحذف الحزمة المرفوعة.

Transbank وWebpay علامتان تجاريتان لمالكيهما. هذه الإضافة غير تابعة لـ Transbank وغير مُعتمَدة من قِبلها.