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 надає Commerce Code після схвалення вашої афілійації, а API Key Secret — після процесу валідації інтеграції (див. документацію для розробників Transbank). Для тестів облікові дані не потрібні. Коди комерції для Webpay Plus Mall, Oneclick та відкладеного списання не підтримуються.

Ліцензійний ключ VibeFox: купується на vibefox.net. Один ключ працює на одному домені.

Встановлення

1. У back office перейдіть до 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.

В Transbank не потрібно налаштовувати URL повернення чи вебхук. Модуль надсилає свій URL повернення з кожною транзакцією.

Під час встановлення модуль створює статус замовлення 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, щоб видалити збережений ключ. Порожнє поле зберігає збережене значення.

URL повернення

Return from Webpay: адреса, на яку Transbank повертає покупця, показана для довідки. Нічого налаштовувати в Transbank не потрібно: модуль надсилає цей URL з кожною транзакцією. Він має бути доступним для покупців; режим обслуговування його не блокує.

Додатково

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 покупець платить кредитною, дебетовою або передплаченою карткою. На цьому етапі замовлення ще не існує.

Коли покупець повертається, модуль підтверджує (commit) транзакцію в Transbank від сервера до сервера. Замовлення позначається оплаченим лише після підтвердження 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 не має вебхука для платежів: результат обробляється, коли покупець повертається з Webpay. Якщо покупець закрив браузер на Webpay і так і не повернувся, транзакція не підтверджується і замовлення не створюється; за словами Transbank, непідтверджені транзакції не проводяться. Модуль не підтримує Webpay Plus Mall, збережені картки Oneclick, підписки, відкладене списання та конвертацію валют.

Замовлення та повернення коштів

Статуси замовлення

No order yet: покупця було відправлено на Webpay, і він не сплатив, скасував, дав формі прострочитися, картку відхилено або платіж ще не вдалося підтвердити. Існує лише кошик.

Payment accepted: Transbank схвалив платіж. Платіж записується з токеном Webpay як ID транзакції, а примітка показує код авторизації, останні чотири цифри картки, buy order, суму, тип платежу та кількість платежів у розстрочку.

Transbank payment on hold: Transbank авторизував платіж, який не відповідає замовленню (сума, buy order або сесія), або купон у кошику перестав бути дійсним після того, як 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 для модуля. Тексти блоку відповідають мові back office (включено англійську та російську).

Якщо ключ не прийнято, блок пояснює причину, наприклад 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 не знає, що ви увійшли в back office, тому спосіб оплати приховано і для вас: налаштувати модуль можна до купівлі ключа, але протестувати його на етапі оформлення замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Існуючі замовлення не зачіпаються: платежі, які вже розпочато, як і раніше підтверджуються, коли покупець повертається з Webpay, а повернення коштів зі сторінки замовлення працюють.

Коли термін дії ліцензії закінчується, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється під час роботи в back office: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

Webpay Plus не відображається на етапі оформлення: перевірте, що ліцензія активна, Enable / Disable увімкнено, валюта кошика CLP і, за вимкненого режиму інтеграції, збережено дійсний Production Commerce Code (12 цифр, що починаються з 5970) та Production API Key Secret. На сторінці налаштувань є попередження для кожної відсутньої умови. У Payment > Preferences перевірте, що модуль дозволено для CLP, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: у Transbank немає вебхука, тож замовлення створюється лише тоді, коли покупець повертається з 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 завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Існуючі замовлення зберігають свої примітки про оплату та ID транзакцій.

Transbank і Webpay є торговельними марками їхніх власників. Цей модуль не пов'язаний із Transbank і не схвалений Transbank.