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

المتطلبات

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

PHP: 8.0 أو أحدث. ترفض الوحدة التثبيت على إصدارات PHP الأقدم.

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

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

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

التثبيت

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

2. عند انتهاء الرفع انقر على Configure، أو ابحث لاحقًا عن VibeFox Transbank Gateway في قائمة الوحدات وانقر على Configure.

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

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

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

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

عند التثبيت تنشئ الوحدة حالة الطلب Transbank payment on hold. يفعّل PrestaShop وحدة الدفع الجديدة لجميع العملات والدول ومجموعات العملاء. يمكنك تقييدها من Payment > Preferences، مع بقاء عملة CLP مسموحًا بها للوحدة.

الإعدادات

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

Transbank Webpay Plus

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

Title: اسم طريقة الدفع الذي يراه العملاء في الدفع، وهو أيضًا الاسم المحفوظ لطريقة الدفع في الطلب. الافتراضي: Webpay Plus. مطلوب: عند الحفظ بعنوان فارغ يظهر Enter a title for the payment method.

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

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

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

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

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

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

Clear saved API key: ضع علامة على Production API Key Secret ثم انقر على Save لحذف المفتاح المحفوظ. يُبقي الحقل الفارغ القيمة المحفوظة.

عنوان العودة

Return from Webpay: العنوان الذي تعيد Transbank العميل إليه، ويُعرض للاطلاع فقط. لا يلزم ضبط أي شيء لدى Transbank: تُرسل الوحدة هذا العنوان مع كل معاملة. يجب أن يكون متاحًا للعملاء؛ ولا يمنعه وضع الصيانة.

متقدم

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

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

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

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

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

الدفع

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

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

إذا فشل طلب التأكيد، مثل انتهاء المهلة، تسأل الوحدة 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. ثم يُنشأ الطلب من الاستجابة المحفوظة دون تأكيد ثانٍ.

إذا ألغى العميل الدفع في 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 جديدة.

إذا تغيّرت السلة بعد بدء الدفع (مثلًا في تبويب آخر، أو أصبحت قسيمة في السلة غير صالحة وأزالها PrestaShop)، لا تُؤكَّد المعاملة، فلا تخصمها Transbank. يرى العميل Your cart 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.

إذا تعذر على 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. ويُكتب السبب التقني في السجل.

تعمل العودة من Webpay أثناء وجود المتجر في وضع الصيانة، ولا يحجبها تقييد الدول الخاص بمتجرك.

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

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

حالات الطلب

No order yet: أُرسل العميل إلى Webpay ولم يدفع، أو ألغى، أو ترك النموذج ينتهي، أو رُفضت البطاقة، أو لم يمكن تأكيد الدفع بعد. لا توجد إلا السلة.

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

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

Refunded: استُرد الدفع بالكامل عبر الوحدة.

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

كتلة Transbank Webpay Plus

تعرض صفحة الطلب كتلة Transbank Webpay Plus تتضمن رقم الطلب (buy order) وبيئته، وحالة الدفع، ورمز الاعتماد، والبطاقة ونوع الدفع مع عدد الأقساط، والمبلغ المخصوم والمسترد، وشارة Integration لمدفوعات الاختبار، وسجل الاستردادات، وWebpay attempts of the cart، وTransbank notes الخاصة بالطلب.

الاستردادات

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

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

لا تُنشئ الوحدة إشعارات دائنة. أزرار الاسترداد القياسية في PrestaShop في صفحة الطلب لا تعيد الأموال عبر Transbank. ولا تُستورَد الاستردادات التي تُجرى في بوابة Transbank إلى PrestaShop.

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

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

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

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

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

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

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

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

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

يرى العميل خطأ عند اختيار Webpay Plus: فعّل 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) أن السلة بعملة أخرى.

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

الطلب في حالة Transbank payment on hold بعد الدفع: اقرأ الملاحظات في كتلة Transbank Webpay Plus (انظر حالات الطلب)، ثم أكمل الطلب أو استرد الدفعة.

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

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

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

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

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

Transbank وWebpay علامتان تجاريتان لمالكيهما. هذه الوحدة غير تابعة لـ Transbank ولا معتمدة من قِبلها.