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. В панели администратора перейдите в 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.