VibeFox Transbank for WooCommerce — Помощь

Требования

WordPress: 6.0 или новее.

WooCommerce: 8.0 или новее, установлен и активен. Плагин не активируется без него.

PHP: 8.0 или новее.

Валюта магазина: чилийское песо (CLP). Webpay Plus списывает только целые песо, поэтому установите Number of decimals в 0 в разделе WooCommerce > Settings > General. В магазинах с другой валютой способ оплаты не отображается.

Счёт Transbank: для реальных платежей нужен стандартный торговый аккаунт Webpay Plus (немедленное списание) с его рабочим Commerce Code и API Key Secret. Transbank выдаёт Commerce Code после одобрения подключения, а API Key Secret — после процесса проверки интеграции (см. документацию для разработчиков Transbank). Для тестов учётные данные не нужны. Коды торговца Webpay Plus Mall, Oneclick и с отложенным списанием не поддерживаются.

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

Установка

1. В WordPress перейдите в Plugins > Add New > Upload Plugin, выберите ZIP-файл плагина и нажмите Install Now. Также можно загрузить папку wcp_transbank_gateway в /wp-content/plugins/ по FTP.

2. Нажмите Activate.

3. Установите валюту магазина — чилийское песо, а Number of decimals — 0 в разделе WooCommerce > Settings > General.

4. Откройте настройки: WooCommerce > Settings > Payments > Transbank Webpay Plus > Manage или нажмите Settings под названием плагина на странице Plugins.

5. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

6. Включите Enable / Disable и проверьте оплату при включённом Integration (test) mode, используя тестовые карты из документации для разработчиков Transbank.

7. Чтобы перейти к реальным платежам, введите Production Commerce Code и Production API Key Secret, снимите флажок Integration (test) mode и сохраните.

В Transbank не нужно настраивать URL возврата или вебхук. Плагин передаёт свой URL возврата с каждой транзакцией.

Настройки

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Transbank Webpay Plus. Над полями страница предупреждает: если выбрана рабочая среда, но Production Commerce Code или API Key отсутствует или недействителен (тогда Webpay скрыт на оформлении заказа); если валюта магазина не CLP (способ оплаты скрыт); и если у цен в CLP есть десятичные знаки (суммы округляются до целых песо). Пока включён режим интеграции, страница показывает Integration (test) environment: реальные деньги не списываются. После сохранения предупреждения учитывают новые настройки. В списке способов оплаты шлюз помечен как требующий настройки, если выбрана рабочая среда без действительных учётных данных.

Общие

Enable / Disable: Enable Transbank Webpay Plus payments включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое видят покупатели на оформлении заказа. По умолчанию: Webpay Plus.

Description: текст под способом оплаты на оформлении заказа. По умолчанию: Pay with credit, debit or prepaid card via Webpay.

Среда и учётные данные

Текст раздела ссылается на документацию для разработчиков Transbank и объясняет, когда Transbank выдаёт рабочие учётные данные.

Integration (test) mode: Use the Transbank integration environment. Платежи идут в тестовую среду интеграции Transbank с её публичным тестовым кодом торговца (597055555532), который заполняется автоматически. Рабочие учётные данные ниже не используются, реальные деньги не списываются. По умолчанию: включено. Снимите флажок, чтобы перейти к реальным платежам.

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

Production API Key Secret: Tbk-Api-Key-Secret вашего рабочего торговца. Храните его в секрете. Пробелы удаляются при сохранении.

Дополнительно

Debug log: Log API requests and returns (errors are always logged). Подробности записываются в WooCommerce > Status > Logs, источник wcp_transbank_gateway; у поля есть ссылка view logs. Ошибки и предупреждения записываются, даже когда эта опция выключена. Данные карт, API-ключи и полные токены в журнал не попадают. По умолчанию: выключено.

Delete data on uninstall: Remove the gateway settings and logs when the plugin is deleted (order data is kept). По умолчанию: выключено.

Тест и рабочая среда

Integration (test) mode определяет, куда идут новые платежи. Каждый платёж запоминает свою среду: подтверждение и возвраты платежа всегда выполняются в той среде (интеграция или рабочая) и с теми учётными данными, с которыми он был создан, даже если вы переключите режим позже.

Оформление заказа

Покупатель выбирает способ оплаты (по умолчанию Webpay Plus) и оформляет заказ. В режиме интеграции на оформлении заказа отображается TEST MODE: Integration environment. Реальных списаний нет. Плагин создаёт транзакцию Transbank на сумму заказа в целых песо (сумма с десятичными знаками округляется до ближайшего песо) и отправляет покупателя на короткую страницу Redirecting to Webpay. Please wait..., которая переадресует его на форму Webpay. Без JavaScript покупатель нажимает Proceed to Webpay. На Webpay покупатель платит кредитной, дебетовой или предоплаченной картой.

Когда покупатель возвращается, плагин подтверждает (commit) транзакцию в Transbank от сервера к серверу. Заказ отмечается оплаченным только после подтверждения Transbank: ответ должен быть одобрен, а сумма, buy order и сессия должны совпадать с тем, что магазин отправил для этой попытки. Затем покупатель видит страницу «Заказ получен». Если запрос подтверждения не прошёл, например из-за тайм-аута, плагин запрашивает у 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.

Если покупатель отменяет оплату на Webpay, форма Webpay истекает или сообщает об ошибке, ничего не списывается. Заказ остаётся в статусе «Ожидает оплаты», а покупатель возвращается на страницу Pay for order с сообщением, например 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.

Каждая попытка Webpay подтверждается не более одного раза. Перезагрузка страницы возврата, кнопка «Назад» в браузере или второй возврат одновременно никогда не подтверждают платёж дважды и не меняют заказ. Если заказ больше не требует оплаты (уже оплачен другой попыткой, отменён или возвращён), поздний возврат не подтверждается, поэтому Transbank его не списывает. Покупатель видит 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. Техническая причина записывается в журнал.

Способ оплаты работает на классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Совместим с WooCommerce High-Performance Order Storage (HPOS).

У Transbank нет вебхука для платежей: результат обрабатывается, когда покупатель возвращается из Webpay. Если покупатель закрыл браузер на Webpay и не вернулся, транзакция не подтверждается, а заказ остаётся в ожидании; по данным Transbank, неподтверждённые транзакции не проходят расчёт. В плагине нет Webpay Plus Mall, сохранённых карт Oneclick, подписок, отложенного списания и конвертации валют.

Заказы и возвраты

Статусы заказа

Pending payment: покупатель был отправлен на Webpay и ещё не заплатил, отменил, позволил форме истечь или платёж пока не удалось подтвердить. Заметка фиксирует каждую закрытую попытку с её buy order.

Processing or Completed: Transbank одобрил платёж. Статус назначает WooCommerce: «В обработке» или «Выполнен» для заказов, содержащих только виртуальные товары для скачивания. В заметке к заказу указаны код авторизации, последние четыре цифры карты, buy order, сумма, тип платежа и количество платежей в рассрочку. ID транзакции — это токен Webpay.

On hold: Transbank авторизовал платёж, который не соответствует заказу (сумма, buy order или ID сессии), например потому что заказ был изменён после начала оплаты. В заметке перечислены расхождения. Проверьте портал Transbank и сделайте возврат или завершите заказ.

Failed: платёж отклонён. Ничего не списано. В заметке указаны код ответа и статус.

Если Webpay возвращает платёж за заказ, который уже оплачен, отменён или возвращён, платёж не подтверждается, а заметка просит проверить портал Transbank, если покупатель сообщает о списании. Существующие заказы последующими попытками не затрагиваются.

Возвраты

Кнопка возврата показывается только для заказов, оплаченных через Webpay. Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Webpay Plus (кнопка использует название способа оплаты). Полные и частичные возвраты поддерживаются в целых песо. Частичная сумма с десятичными знаками отклоняется сообщением Webpay refunds are in whole Chilean pesos. Please enter an amount without decimals. Остаток от суммы заказа с десятичными знаками округляется так же, как списание. Возврат выполняется в той среде, где был произведён платёж, поэтому в рабочей среде должны быть указаны рабочие учётные данные.

Transbank отвечает реверсом (REVERSED) или аннулированием (NULLIFIED). Успешный возврат добавляется в заметки к заказу с суммой, типом, кодом авторизации и остатком в Transbank. Если Transbank не принимает возврат, WooCommerce показывает ошибку и возврат не фиксируется. Возвраты, сделанные в портале Transbank, в WooCommerce не импортируются.

Лицензионный ключ

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > Transbank Webpay Plus. Вставьте ключ в поле License key и нажмите Activate. В блоке показан статус, например дата, до которой активна лицензия, и ваш домен. Используйте Check now, чтобы снова проверить статус, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

Один ключ работает на одном домене. Удаление ключа с сайта не освобождает место под домен. Освободите место в своём аккаунте на vibefox.net.

Без активного ключа Webpay Plus не показывается покупателям на оформлении заказа. Если платёж всё же запущен, покупатель видит This payment method is not available. Please choose another one. Администраторы магазина, вошедшие в систему, по-прежнему видят способ оплаты с пометкой (unlicensed — visible to admins only), чтобы вы могли настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице Plugins и на страницах WooCommerce. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты работают.

Когда лицензия истекает, плагин продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется в фоновом режиме.

Устранение неполадок

Webpay Plus не появляется на оформлении заказа: проверьте, что лицензия активна, Enable / Disable включено, валюта магазина CLP (на странице Pay for order — валюта заказа) и, при выключенном режиме интеграции, что сохранены действительный Production Commerce Code (12 цифр, начинается с 5970) и Production API Key Secret. На странице настроек для каждого отсутствующего условия отображается предупреждение.

Платёж прошёл, но заказ остаётся в статусе Pending payment: у Transbank нет вебхука, поэтому заказ подтверждается только при возврате покупателя из Webpay. Если покупатель закрыл браузер на Webpay, транзакция не была подтверждена и, по данным Transbank, не проходит расчёт. Проверьте заметки к заказу, журнал и транзакцию в портале Transbank.

Покупатель видит We could not confirm your Webpay payment with Transbank: запрос подтверждения не прошёл, и статус не удалось проверить. Заказ не изменён, добавлена заметка. Покупатель может повторить попытку через некоторое время. Если портал Transbank показывает транзакцию как авторизованную, подтвердите её там до отправки.

Покупатель видит ошибку при оформлении заказа: включите Debug log и посмотрите WooCommerce > Status > Logs, источник wcp_transbank_gateway. Сообщение Webpay payments are not available at the moment обычно означает неверные рабочие учётные данные. Could not connect to Webpay означает, что Transbank не удалось достичь. Заказ в валюте, отличной от CLP, нельзя оплатить через Webpay.

Суммы и возвраты отличаются на несколько песо: цены в CLP имеют десятичные знаки. Webpay списывает целые песо, поэтому суммы округляются. Установите Number of decimals в 0.

Возврат не проходит с ошибкой The production Commerce Code / API Key are missing: платёж был сделан в рабочей среде, а рабочие учётные данные не сохранены. Введите их и повторите попытку.

Возврат не проходит с ошибкой Transbank refused the refund или Transbank did not approve the refund: Transbank не принял возврат; в сообщении указаны причина или тип и код ответа. Ничего не возвращено. Проверьте транзакцию в портале Transbank.

Блок лицензии показывает ошибку: следуйте сообщению в блоке. Например, если ключ уже используется на другом домене, освободите место в аккаунте на vibefox.net и нажмите Check now. Если адрес сайта изменился, нажмите Check now, чтобы активировать ключ для нового домена. Если сервер лицензий недоступен, плагин продолжает работать по последнему известному статусу.

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить его, деактивируйте и удалите плагин на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза, остальные опции и временные данные плагина, а также его журналы (файлы логов, включая ротированные, и записи журнала в базе данных) удаляются только если была включена опция Delete data on uninstall. Иначе они сохраняются для повторной установки. Данные Transbank, сохранённые в заказах, всегда остаются, так как они нужны для бухгалтерии и возвратов. Существующие заказы сохраняют свои заметки об оплате и ID транзакций.

Transbank и Webpay являются товарными знаками их соответствующих владельцев. Этот плагин не связан с Transbank и не одобрен Transbank.