VibeFox Datatrans for WooCommerce — Помощь

Требования

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

WooCommerce: 7.0 или новее, установлен и активен.

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

HTTPS: ваш сайт должен быть доступен из интернета по HTTPS, чтобы Datatrans могла доставлять вебхуки.

Учётная запись Datatrans: вам понадобятся Merchant ID, пароль API для обмена между серверами и, желательно, ключ подписи HMAC-SHA256 для вебхуков. Учётные данные sandbox берутся в Web Admin sandbox Datatrans (admin.sandbox.datatrans.com), рабочие — в рабочем Web Admin (admin.datatrans.com). Sandbox и рабочая среда — это отдельные учётные записи Datatrans с разными Merchant ID и ключами.

Валюта: валюта магазина (или валюта заказа вашего мультивалютного плагина) должна быть включена для вашей учётной записи мерчанта Datatrans.

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

Установка

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

2. Нажмите Activate. WooCommerce должен быть активен.

3. Откройте настройки: WooCommerce > Settings > Payments > Datatrans > Manage, либо нажмите Settings под названием плагина на странице «Плагины».

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

5. Введите учётные данные sandbox и, для реальных платежей, рабочие учётные данные (см. раздел «Настройка»).

6. Включите Enable/Disable. Держите Sandbox mode включённым на время тестов, затем снимите флажок, чтобы принимать реальные платежи.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Datatrans. Если шлюз включён, но не заполнены Merchant ID или пароль API текущей среды, страница показывает Datatrans is hidden at checkout until these settings are filled in: со списком недостающих полей. Пока включён режим sandbox, она показывает Sandbox mode is on: payments go to the Datatrans sandbox, no real money is charged.

Вебхук

Webhook URL показан вверху настроек. Он выглядит так: https://your-site/wc-api/datatrans_payment_callback/. Плагин отправляет этот адрес в Datatrans с каждой транзакцией, поэтому вводить его где-либо не нужно. Вы также можете указать его в настройках вебхука в Web Admin Datatrans, чтобы получать обновления о списаниях и отменах, выполненных там.

Вебхук сообщает состояние транзакции. Плагин реагирует на следующие состояния:

settled / transmitted: платёж списан. Заказ отмечается оплаченным.

authorized: платёж авторизован, но не списан (только когда Auto settle выключен). Заказ переводится в статус «На удержании».

failed: платёж не прошёл или был отклонён. Заказ получает статус «Не удался» и может быть оплачен снова.

canceled: покупатель отменил оплату на платёжной странице (заказ остаётся в статусе «В ожидании оплаты») либо авторизация была снята (заказ отменяется).

При наличии ключа подписи HMAC каждый вебхук проверяется по заголовку Datatrans-Signature. Вебхуки без действительной подписи отклоняются. Без ключа подписи плагин не доверяет содержимому вебхука и сверяет каждый вебхук со статусным API Datatrans. Без вебхука заказ подтверждается только тогда, когда покупатель возвращается в магазин после оплаты.

Общие

Enable/Disable: Enable Datatrans Payment включает или выключает способ оплаты. По умолчанию: выключено.

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

Description: текст, показываемый под способом оплаты при оформлении заказа. По умолчанию: Pay securely via Datatrans.

Sandbox mode: Use the Datatrans sandbox (test payments, no real money). Переключает и хосты API и платёжной страницы, и приведённые ниже учётные данные. Возвраты и списания всегда используют ту среду, где был сделан платёж. По умолчанию: включено. Снимите флажок, чтобы принимать реальные платежи.

Учётные данные sandbox

Скопируйте их из Web Admin sandbox Datatrans (admin.sandbox.datatrans.com). Ключ подписи находится там в настройках безопасности.

Sandbox merchant ID: Merchant ID вашей учётной записи sandbox.

Sandbox API password: пароль API для обмена между серверами вашей учётной записи sandbox.

Sandbox HMAC sign key: шестнадцатеричный ключ для проверки заголовка Datatrans-Signature вебхуков. Без него каждый вебхук повторно сверяется со статусным API Datatrans.

Рабочие учётные данные

Скопируйте их из рабочего Web Admin Datatrans (admin.datatrans.com).

Production merchant ID: Merchant ID вашей рабочей учётной записи.

Production API password: пароль API для обмена между серверами вашей рабочей учётной записи.

Production HMAC sign key: шестнадцатеричный ключ для проверки заголовка Datatrans-Signature рабочих вебхуков. Без него каждый вебхук повторно сверяется со статусным API Datatrans.

Ключ подписи должен быть шестнадцатеричной строкой в том виде, в каком его выдаёт Datatrans. Любое другое значение не сохраняется: страница показывает ошибку и оставляет прежнее значение. Если вы обновляетесь с версии 1.0, единственный набор учётных данных той версии переносится в поля sandbox, если режим sandbox был включён; иначе он остаётся в рабочих полях.

Обработка платежа

Auto settle: Capture (settle) payments immediately. По умолчанию: включено. Если выключить, платежи только авторизуются: заказ переводится в статус «На удержании», а списать платёж вы можете позже действием заказа Capture Datatrans payment или снять авторизацию через Cancel Datatrans authorization.

Order status after payment: статус заказа, устанавливаемый после расчёта по платежу. Статус устанавливается сразу, без второй смены статуса.

Processing: значение WooCommerce по умолчанию (по умолчанию). Заказы только с виртуальными загружаемыми товарами получают статус «Выполнен».

Completed: каждый оплаченный заказ получает статус «Выполнен».

On Hold: каждый оплаченный заказ ожидает вашей ручной проверки.

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

Logging: Log payment events and API calls записывает подробности в WooCommerce > Status > Logs, источник wcp_datatrans_gateway. Ошибки записываются всегда. Ключи, данные карт и данные покупателей не записываются. По умолчанию: выключено.

Delete data on uninstall: Remove the plugin settings when the plugin is deleted. По умолчанию: выключено.

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

Покупатель выбирает способ оплаты (по умолчанию Datatrans) и оформляет заказ. Плагин создаёт транзакцию Datatrans на сумму заказа в валюте заказа, с ID заказа в качестве ссылки, и отправляет покупателя на платёжную страницу Datatrans. Там покупатель платит любым способом, включённым в вашей учётной записи Datatrans, например картой, через TWINT или PostFinance. Платёжная страница открывается на немецком, английском, французском или итальянском, если ваш сайт использует один из этих языков; иначе язык выбирает Datatrans.

После оплаты покупатель возвращается на страницу полученного заказа вашего магазина. Заказ отмечается оплаченным только после подтверждения от Datatrans: через вебхук или через серверный запрос к статусному API Datatrans, когда покупатель возвращается. Адрес возврата содержит ключ заказа, а само возвращение никогда не отмечает заказ оплаченным.

Если покупатель отменяет оплату на платёжной странице, он попадает на страницу Pay for order с сообщением The payment was canceled. You can try again or choose another payment method. После неудавшегося платежа сообщение такое: The payment was not completed. Please try again or choose another payment method. Заказ остаётся доступным для оплаты, и покупатель может попробовать снова.

Если Datatrans не может начать платёж, покупатель видит The payment could not be started. Please try again or choose another payment method. Причина записывается в журнал.

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

Плагин принимает только разовые платежи на платёжной странице Datatrans. В нём нет сохранённых карт и алиасов, подписок, интеграции Lightbox или Secure Fields, выбора способов оплаты в настройках и частичного списания по авторизации.

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

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

Pending payment: покупатель отправлен в Datatrans и ещё не оплатил, отменил оплату на платёжной странице либо Datatrans ещё не подтвердила платёж. Каждая новая транзакция отмечается в заказе с её ID и средой.

Processing, Completed or On Hold: расчёт по платежу выполнен. Статус соответствует параметру Order status after payment. Заметка заказа показывает сумму, способ оплаты, ID транзакции Datatrans и среду (sandbox или рабочая). ID транзакции сохраняется в заказе.

On hold, authorized: при выключенном Auto settle платёж авторизован, но не списан. Откройте заказ и выберите Capture Datatrans payment или Cancel Datatrans authorization в действиях заказа. Списание использует текущую сумму заказа, которая не должна превышать авторизованную сумму. Если превышает, либо если Datatrans отклоняет списание или отмену, причина добавляется в заметки заказа.

On hold after payment: Datatrans сообщила сумму или валюту, отличающиеся от суммы заказа (например, заказ был изменён после начала платежа), либо платёж пришёл после отмены заказа. Заметка заказа это объясняет. Проверьте транзакцию в Web Admin Datatrans и выполните заказ или верните платёж.

Failed: платёж не прошёл или был отклонён. Покупатель может попробовать снова.

Cancelled: авторизация снята действием заказа или в Web Admin Datatrans.

Запоздавшее уведомление о неудаче или отмене никогда не меняет оплаченный заказ. Если по уже оплаченному заказу приходит второй успешный платёж, заказ не меняется. Заметка предупреждает о возможном двойном списании и просит вас при необходимости вернуть его в Datatrans.

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Datatrans. Поддерживаются полные и частичные возвраты. Возврат отправляется в ту среду, где был сделан платёж, поэтому учётные данные этой среды должны быть заданы. Повторная попытка возврата не зачисляется дважды. Если Datatrans не принимает возврат, WooCommerce показывает ошибку, и возврат не записывается. Успешный возврат добавляется в заметки заказа с суммой и ID транзакции возврата Datatrans.

Для платежа, который только авторизован, возврат полной суммы отменяет авторизацию. Частичный возврат невозможен, пока платёж не списан.

Возвраты, сделанные в Web Admin Datatrans, в WooCommerce не записываются. При необходимости создайте ручной возврат в WooCommerce без Refund via Datatrans.

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

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

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

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

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

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

Datatrans не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включён, а Merchant ID и пароль API текущей среды заданы: поля sandbox в режиме sandbox, иначе рабочие поля. Страница настроек перечисляет недостающие поля.

Платёж прошёл, но заказ остаётся в статусе «В ожидании оплаты»: Datatrans не смогла обратиться к URL вебхука, а покупатель не вернулся в магазин. Проверьте, что сайт доступен из интернета по HTTPS и что ни плагин безопасности, ни брандмауэр не блокируют запросы к /wc-api/datatrans_payment_callback/. Проверьте, что ключ подписи в настройках относится к среде платежа. Включите Logging и посмотрите WooCommerce > Status > Logs, источник wcp_datatrans_gateway.

Вебхук отвечает Invalid signature: ключ подписи HMAC в настройках не совпадает с ключом в Web Admin Datatrans или относится к другой среде. Скопируйте ключ заново.

Вебхук отвечает Not configured или Verification failed: вебхук нужно было проверить по статусному API Datatrans, но учётные данные этой среды отсутствуют или Datatrans не ответила. Datatrans повторяет вебхук.

Ключ подписи HMAC не сохраняется: ключ должен быть шестнадцатеричной строкой. Скопируйте его заново из Web Admin Datatrans.

Покупатель видит The payment could not be started: Merchant ID или пароль API неверны, относятся к другой среде, либо валюта не включена для вашей учётной записи Datatrans. Включите Logging, чтобы увидеть причину.

После оплаты заказ в статусе «На удержании»: прочитайте заметку заказа. Оплаченная сумма или валюта отличались от заказа, платёж пришёл после отмены заказа, либо платёж только авторизован и ожидает списания.

Списание невозможно: сумма заказа больше авторизованной. Списание использует текущую сумму заказа, поэтому уменьшите её до авторизованной суммы или меньше.

Возврат завершается ошибкой с сообщением об учётных данных: платёж был сделан в другой среде, и её учётные данные не заданы. Введите их и повторите попытку. Для авторизованного платежа верните полную сумму или сначала спишите его.

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

Для разработчиков: в readme упомянут фильтр wcp_datatrans_gateway_init_request, например, чтобы ограничить способы оплаты, показываемые на странице Datatrans.

Удаление

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

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