VibeFox Datatrans for PrestaShop — Помощь

Требования

PrestaShop: 8.0 – 9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более ранних версиях PHP.

Учётная запись 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. В админ-панели откройте Modules > Module Manager и нажмите Upload a module. Выберите ZIP-архив модуля.

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Datatrans Gateway в списке модулей и нажмите Configure.

3. Вставьте лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы Configure и нажмите Activate (см. раздел «Лицензионный ключ»).

4. Введите учётные данные sandbox из Web Admin sandbox Datatrans (см. Настройки).

5. Включите Enable/Disable и нажмите Save. Выполните тестовый платёж в режиме sandbox. Когда всё заработает, введите учётные данные рабочей среды и выключите Sandbox mode.

При установке модуль создаёт статус заказа Datatrans payment on hold. PrestaShop по умолчанию включает новый платёжный модуль для всех валют, стран и групп покупателей. Ограничить их можно в Payment > Preferences; Datatrans показывается только для валют, разрешённых там.

Настройки

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Datatrans Gateway > Configure. У каждого раздела есть собственная кнопка Save, которая сохраняет всю страницу. Если способ оплаты включён, но в текущей среде не заполнены 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.

Datatrans

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

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

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

Sandbox mode: использует sandbox Datatrans: тестовые платежи, реальные деньги не списываются. Переключатель меняет и серверы Datatrans, и учётные данные, которые используются для новых платежей. По умолчанию: включено. Выключите его, чтобы принимать реальные платежи. Пока он включён, покупатели видят под способом оплаты Sandbox mode: no real payment is taken. Возвраты и списания всегда используют ту среду, в которой был сделан платёж, независимо от положения этого переключателя.

Учётные данные 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.

Сохранённые пароли и ключи подписи больше никогда не показываются. Поле остаётся пустым и отображает Saved — leave empty to keep it. Вводите новое значение только для его изменения. Ключ подписи должен быть шестнадцатеричной строкой, выданной Datatrans. Любое другое значение не сохраняется: страница показывает ошибку и оставляет прежнее значение, а остальные настройки сохраняются.

Clear saved secrets: отметьте пароль или ключ подписи и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

URL вебхука

В этом разделе показан URL вебхука вашего магазина. При включённых понятных URL он выглядит так: https://your-shop/module/wcp_datatrans_gateway/webhook, возможно, с кодом языка, например /en/. Модуль передаёт этот URL в Datatrans с каждой транзакцией, поэтому вводить его никуда не нужно. Его также можно указать в настройках вебхуков Web Admin Datatrans, чтобы получать обновления о списаниях и отменах, сделанных там; копируйте его точно в том виде, в каком его показывают настройки. Возвраты, выполненные в Web Admin Datatrans, в заказе не отображаются.

Вебхук сообщает о состоянии транзакции. Модуль действует в зависимости от следующих состояний:

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

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

Auto settle: списывает (подтверждает) платежи сразу. Если выключено, платежи только авторизуются: заказ переводится в статус Datatrans payment on hold, и вы списываете его позже действием Capture Datatrans payment в блоке Datatrans заказа или снимаете авторизацию действием Cancel Datatrans authorization. По умолчанию: включено.

Order status after payment: статус заказа после подтверждения платежа.

Платежи только с авторизацией и несоответствия суммы или валюты всегда переводятся в Datatrans payment on hold.

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

Logging: записывает события платежей и вызовы API в файл logs/datatrans_p_debug.log.php в папке модуля. Файл нельзя открыть через браузер. Ошибки записываются всегда, даже когда этот переключатель выключен. Ключи, данные карт и данные покупателей не записываются. По умолчанию: выключено.

Log: показывает размер и последние записи журнала, а также кнопку для его очистки.

Delete data on uninstall: если включено, при удалении модуля удаляются его настройки и журнал. Записи о платежах Datatrans в заказах (транзакции, возвраты) и статус заказа всегда сохраняются. По умолчанию: выключено.

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Datatrans) и видит примечание You will be redirected to the Datatrans payment page to complete the payment securely. После подтверждения модуль создаёт транзакцию Datatrans на сумму корзины в валюте корзины и отправляет покупателя на платёжную страницу Datatrans. Страница открывается на немецком, английском, французском или итальянском языке, если язык магазина является одним из них. Там покупатель оплачивает любым способом, включённым в вашей учётной записи Datatrans. На этом этапе заказа ещё не существует.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Datatrans: вебхуком или серверным запросом к API статусов Datatrans, когда покупатель возвращается. Адрес возврата содержит защищённый ключ корзины, а само возвращение никогда не создаёт заказ. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением Your payment with Datatrans has been received. При платеже только с авторизацией страница показывает Your payment with Datatrans has been authorized. The amount will be charged when your order is processed. Если Datatrans ещё не подтвердил платёж, страница Payment confirmation показывает Your payment is being confirmed by Datatrans. You will receive an e-mail as soon as it is confirmed. Please do not pay again. с кнопкой Check again; вебхук создаст заказ сразу, как только придёт.

Если покупатель отменяет платёж на странице Datatrans, он возвращается к оформлению заказа с сообщением 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; поздний платёж по предыдущей попытке по-прежнему распознаётся.

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

Вебхук работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по странам вашего магазина.

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

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

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

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

Payment accepted, Delivered или Datatrans payment on hold: платёж подтверждён. Статус следует за Order status after payment. Платёж фиксируется с ID транзакции Datatrans, а заметка показывает сумму, способ оплаты, среду и способ подтверждения (вебхук или возврат).

Datatrans payment on hold после авторизации: Auto settle выключено, и платёж только авторизован. Списать или отменить его можно в блоке заказа.

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

Canceled: авторизация снята в блоке заказа или в Web Admin Datatrans.

Refunded: платёж полностью возвращён через модуль.

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

Блок Datatrans payment

На странице заказа отображается блок Datatrans payment с ID транзакции, статусом Datatrans, способом оплаты, суммой, оплаченными и возвращёнными суммами, значком Sandbox для платежей sandbox, историей возвратов и Datatrans notes заказа. Действия блока требуют права на редактирование заказов; доступ к страницам модулей не нужен.

Списание и отмена

Для платежа только с авторизацией блок показывает Capture Datatrans payment и Cancel Datatrans authorization. Списание проводит платёж на текущую сумму заказа, которая не должна превышать авторизованную сумму; затем заказ переходит в статус из Order status after payment. Отмена снимает авторизацию и переводит заказ в статус Canceled. Обе операции выполняются в среде платежа. Если Datatrans отказывает, блок показывает ошибку, и добавляется заметка.

Возвраты

В блоке Datatrans payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину и нажмите Refund via Datatrans. Подтвердите вопрос Refund this amount through Datatrans? This cannot be undone. Поддерживаются полные и частичные возвраты в пределах суммы, которую Datatrans фактически списал, за вычетом предыдущих возвратов. Возврат отправляется в среду платежа, поэтому в ней должны быть заполнены Merchant ID и пароль API. Повторно отправленный возврат не зачисляется дважды. Если Datatrans не принимает возврат, блок показывает ошибку, и возврат не фиксируется. Успешный возврат добавляется в историю и заметки вместе с ID транзакции возврата Datatrans. Полный возврат переводит заказ в статус Refunded; частичный возврат статус не меняет.

При платеже только с авторизацией ещё ничего не списано: «вернуть» можно только полную сумму, и это снимает авторизацию. Возвраты доступны после того, как Datatrans подтвердил платёж; авторизацию с несовпадающей суммой нельзя вернуть до подтверждения.

Модуль не создаёт кредит-ноты (credit slips). Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Datatrans. Возвраты, сделанные в Web Admin Datatrans, в PrestaShop не фиксируются.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Datatrans Gateway — первый блок на странице Modules > Module Manager > VibeFox Datatrans Gateway > Configure, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-datatrans и ссылка Manage licenses and domains in your account, которая открывает вашу учётную запись vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока следуют языку панели администратора (включены английский и русский).

Если ключ не принят, блок показывает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в вашей учётной записи нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

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

Без активного ключа Datatrans не показывается покупателям на оформлении заказа. Если оплата всё же начата, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в панель администратора, поэтому способ оплаты скрыт и для вас: настроить модуль можно до покупки ключа, но проверить его на оформлении заказа нельзя. Напоминание появляется в Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются, а возвраты работают.

Когда лицензия истекает, модуль продолжает работать, но для обновлений и поддержки нужно продление. Статус автоматически проверяется во время работы в панели администратора: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

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

Datatrans does not appear at checkout: проверьте, что лицензия активна, Enable/Disable включено, а в текущей среде заполнены Merchant ID и пароль API: поля sandbox в режиме sandbox, поля рабочей среды в остальных случаях. На странице настроек перечислены недостающие поля. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

The payment went through, but no order was created: Datatrans не смог достучаться до URL вебхука, а покупатель не вернулся в магазин. Проверьте, что магазин доступен из интернета и что брандмауэр не блокирует запросы к URL вебхука. Проверьте, что ключ подписи в настройках принадлежит среде платежа. Посмотрите поле Log на странице модуля.

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

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

Webhook answers Busy, retry: заказ в этот момент подтверждался другим запросом или заказ не удалось создать (например, модуль отключён). Datatrans повторит вебхук. Журнал показывает причину.

The webhook URL shows Method not allowed in the browser: это нормально. URL принимает только запросы от Datatrans.

The HMAC sign key is not saved: ключ должен быть шестнадцатеричной строкой. Скопируйте его заново из Web Admin Datatrans.

The customer sees Datatrans payments are not configured yet: не заполнены Merchant ID или пароль API текущей среды.

The customer sees The payment could not be started: посмотрите поле Log. Типичные причины: неверные Merchant ID или пароль API либо учётные данные не той среды.

Order is Datatrans payment on hold after payment: прочитайте Datatrans notes в блоке заказа (см. Статусы заказа), затем выполните заказ или верните платёж.

Capture is refused: сумма заказа больше авторизованной суммы. Datatrans не может списать больше, чем было авторизовано.

Refund or capture fails with a message about missing credentials: платёж был сделан в другой среде, и её Merchant ID или пароль API не заполнены. Введите их и повторите попытку.

Удаление

Откройте Modules > Module Manager, откройте меню рядом с VibeFox Datatrans Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete data on uninstall включено, настройки модуля и журнал удаляются. Если выключено, все настройки сохраняются для последующей переустановки. Транзакции и возвраты Datatrans, а также статус заказа Datatrans payment on hold всегда сохраняются, поэтому заказы, оплаченные ранее, можно вернуть или списать и после переустановки. Существующие заказы сохраняют свои платёжные заметки и ID транзакций.

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