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 не нужно. Расширение передаёт свой адрес возврата с каждой транзакцией. Новая установка начинает работу с выключенным способом оплаты и включённым режимом интеграции.

Настройка

Все настройки находятся на странице расширения: 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 ничего настраивать не нужно: расширение передаёт этот адрес с каждой транзакцией (у Transbank нет вебхука: платёж подтверждается, когда покупатель возвращается). Адрес должен быть доступен из интернета; режим обслуживания его не блокирует (в 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 или session). Примечание перечисляет расхождения. Проверьте портал 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.