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). Для тестів облікові дані не потрібні. Коди Commerce для 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. Сторінка налаштувань і її поля однакові в обох версіях. Відрізняється лише URL повернення (див. URL повернення).

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

Налаштування

Усі налаштування розташовані на сторінці розширення: Extensions > Extensions > Payments > VibeFox Transbank Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка попереджає вас, коли вибрано робочий режим, але Commerce Code або API Key для продакшену відсутній чи недійсний (тоді Webpay приховується під час оформлення замовлення), коли валюта магазину за замовчуванням не CLP (спосіб оплати приховується для інших валют), і коли CLP має знаки після коми (суми округлюються до цілих песо). Поки ввімкнено режим інтеграції, сторінка повідомляє, що платежі надсилаються до інтеграційного середовища Transbank із публічним тестовим кодом Commerce і що реальні кошти не списуються. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

Під час збереження 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 із його публічним тестовим кодом Commerce (597055555532), який використовується автоматично. Робочі облікові дані нижче не використовуються, і реальні кошти не списуються. За замовчуванням: on. Вимкніть, щоб перейти в робочий режим. Поки він увімкнений, покупці на кроці Confirm Order бачать TEST MODE — інтеграційне середовище. Реальних списань немає.

Production Commerce Code: ваш робочий код Commerce (Tbk-Api-Key-Id): 12 цифр, що починаються з 5970. Якщо ваш код має 8 цифр, введіть його як є; префікс 5970 додається під час збереження. Пробіли та інші символи видаляються. Публічні тестові коди Commerce від Transbank не працюють у робочому режимі: з будь-яким із них Webpay залишається прихованим під час оформлення замовлення.

Production API Key Secret: Tbk-Api-Key-Secret вашого робочого Commerce. Тримайте його в таємниці. Пробіли видаляються під час збереження. Збережений ключ більше ніколи не показується: поле лишається порожнім і відображає Saved — leave empty to keep it. Вводьте нове значення лише тоді, коли хочете його змінити. Щоб видалити збережений ключ, відмітьте Clear saved API key і натисніть Save.

Integration (test) mode визначає, куди надходять нові платежі. Кожен платіж запам’ятовує своє середовище: підтвердження та повернення коштів за платежем завжди виконуються в тому середовищі (інтеграційному або робочому) і з тими обліковими даними, з якими платіж було створено, навіть якщо ви пізніше змінете режим.

URL повернення

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

Замовлення

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 немає вебхука платежів: результат обробляється, коли покупець повертається з 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 немає вебхука, тому замовлення отримує статус лише тоді, коли покупець повертається з 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 увімкнено, видаляються інші налаштування шлюзу (title, description, режим інтеграції, облікові дані, перемикач журналу налагодження) та журнал. Якщо вимкнено, вони зберігаються для подальшої повторної інсталяції. Спроби Webpay та повернення коштів за замовленнями завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторної інсталяції. Наявні замовлення зберігають свої примітки про оплату.

В OpenCart 4, щоб також видалити файли розширення, після цього перейдіть до Extensions > Installer і натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox Transbank Gateway у списку встановлених розширень, а потім Delete (червона кнопка з кошиком), щоб видалити завантажений пакет.

Transbank і Webpay є торговими марками їхніх власників. Це розширення не пов’язане з Transbank і не схвалене Transbank.