VibeFox Paytrail for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Валюта: EUR. Paytrail принимает только евро. Для корзины в любой другой валюте способ оплаты скрывается на оформлении заказа. Суммы передаются в центах.

Доступ к магазину из интернета: Paytrail подтверждает каждый платёж callback-запросом сервер-сервер, поэтому магазин должен быть доступен из интернета. Без callback-запросов заказы всё равно создаются, когда покупатель возвращается из Paytrail.

Аккаунт Paytrail: нужны ваши Merchant ID и секретный ключ (Secret key), которые показаны в панели мерчанта Paytrail (данные аккаунта или интеграции). Для тестирования аккаунт не нужен: в тестовом режиме используется публичный тестовый аккаунт Paytrail. Сами способы оплаты включаются в вашем аккаунте Paytrail.

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

Установка

1. В Back Office перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

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

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

4. Чтобы сначала попробовать модуль, включите Test mode. Для реальных платежей выключите его и введите Merchant ID и Secret key. Callback-URL в Paytrail настраивать не нужно.

5. Включите Enable/Disable и нажмите Save.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Paytrail Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает Test mode is active. Payments use the public Paytrail test account — no real money is charged., пока включён тестовый режим. В боевом режиме страница предупреждает, если не заполнены Merchant ID или Secret key, если в качестве Merchant ID указан публичный тестовый аккаунт 375917, а также если валюта магазина не EUR. Во всех этих случаях Paytrail не показывается на оформлении заказа.

При сохранении Merchant ID, содержащий что-либо кроме цифр, не сохраняется: появляется ошибка Paytrail merchant ID must contain digits only. The previous value was kept.. Поле Title не может быть пустым.

Paytrail

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

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

Description: текст, который покупатель видит под способом оплаты при оформлении заказа. По умолчанию: Pay securely with Finnish online banking, card, mobile payment or invoice on the Paytrail payment page.

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

Ваш Merchant ID и секретный ключ показаны в панели мерчанта Paytrail (данные аккаунта или интеграции). Раздел содержит ссылку на панель мерчанта. Поддерживаются только платежи в EUR.

Test mode: использует публичный тестовый аккаунт Paytrail (Merchant ID 375917) для новых платежей вместо ваших собственных учётных данных. Реальные деньги не списываются, ключи не нужны. Покупатели видят Test mode: no real payment will be made. под способом оплаты. Секретный ключ тестового аккаунта общедоступен, поэтому любой может имитировать платёж, сделанный в тестовом режиме. Никогда не оставляйте тестовый режим включённым в боевом магазине. По умолчанию: off.

Merchant ID: ваш Merchant ID Paytrail (только цифры). Используется, когда тестовый режим выключен.

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

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

Callback-запросы и возвраты всегда используют учётные данные того режима, в котором был совершён платёж, поэтому переключение между тестовым и боевым режимом не ломает старые заказы.

Заказы

Callback URL: показывает адрес, по которому Paytrail подтверждает каждый платёж по схеме сервер-сервер. С понятными URL он выглядит так: https://your-shop/module/wcp_paytrail_gateway/callback. Он передаётся с каждым платежом, поэтому в панели Paytrail ничего настраивать не нужно, но магазин должен быть доступен из интернета.

Order status after payment: статус оплаченного заказа.

Ожидающие платежи находятся в статусе Awaiting Paytrail payment. Расхождения по сумме и другие проблемы всегда переводят заказ в статус Paytrail payment on hold.

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

Debug log: записывает запросы к API и callback-запросы в файл logs/ptg_debug.log.php в папке модуля. Файл нельзя открыть через браузер. Персональные данные и ключи не записываются. Ошибки и предупреждения записываются всегда. По умолчанию: off.

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

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

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Paytrail) и подтверждает выбор. Модуль создаёт платёж Paytrail на сумму корзины в евро и отправляет с ним строки заказа: товары после правил корзины, доставку и подарочную упаковку, каждую со своей ставкой НДС с точностью до одного десятичного знака. Строки всегда дают в сумме сумму платежа; разница округления включается в одну из строк или отправляется отдельной строкой Rounding. Адреса для выставления счёта и доставки отправляются только тогда, когда они полные, а слишком длинные значения сокращаются до ограничений Paytrail. Язык платёжной страницы — финский, шведский или английский, в зависимости от языка корзины. На этом этапе заказа ещё не существует.

Покупатель переходит на платёжную страницу Paytrail, выбирает способ оплаты, включённый для вашего аккаунта Paytrail, и платит. Затем Paytrail подтверждает платёж дважды: возвращает покупателя в ваш магазин и вызывает callback-URL по схеме сервер-сервер. Оба подтверждения принимаются только с действительной подписью, сделанной учётными данными этой попытки оплаты, и только для попытки, созданной для этой корзины. Оплаченная сумма сравнивается с итогом корзины. Заказ помечается как оплаченный только после такого подтверждения Paytrail. Модуль обрабатывает следующие статусы Paytrail:

После успешной оплаты покупатель видит стандартную страницу подтверждения заказа с текстом Your Paytrail payment has been received. Для ожидающего платежа страница показывает Your Paytrail payment is pending confirmation by the payment provider. The order is updated automatically — please do not pay again. Если callback как раз в этот момент фиксирует платёж, страница Payment confirmation просит покупателя не платить повторно и предлагает кнопку Check again.

После отменённого или неудачного платежа покупатель возвращается к оформлению заказа с сообщением The Paytrail payment was cancelled or failed. You can try again or choose another payment method. Если платёж ещё не завершён, сообщение такое: The Paytrail payment has not been completed yet. You can try again or choose another payment method. Корзина сохраняется. Возврат, который не удалось проверить, показывает Payment verification failed. и ничего не меняет.

Если Paytrail не может начать платёж, покупатель остаётся на оформлении заказа с коротким сообщением, например Could not connect to Paytrail. Please try again in a moment., Paytrail is temporarily unavailable. Please choose another payment method. (неверные учётные данные) или Paytrail could not start the payment. Please check your billing details and try again, or choose another payment method. Техническая причина записывается в журнал. Сумма вне ограничений Paytrail показывает This order total cannot be paid with Paytrail. Please choose another payment method.

Платёж Paytrail нельзя отменить через API. Каждая новая попытка для корзины — это новый платёж Paytrail. Если покупатель также оплатит более старую, но ещё открытую платёжную страницу, второй платёж отмечается в заказе как дубликат, подлежащий возврату.

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

Покупатель выбирает способ оплаты на странице Paytrail, а не в вашем оформлении заказа. Модуль не поддерживает токенизацию карт и сохранённые карты, подписки, shop-in-shop, ручную активацию счетов и отчёты о взаиморасчётах.

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

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

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

Payment accepted or Delivered: платёж подтверждён. Статус следует за Order status after payment. Платёж записывается с идентификатором транзакции Paytrail, а примечание показывает транзакцию, способ оплаты в Paytrail и сумму.

Awaiting Paytrail payment: платёж ожидает у провайдера (счёт или отложенный платёж). Заказ переходит в оплаченный статус, когда Paytrail подтверждает платёж, или в Payment error, если платёж не прошёл.

Paytrail payment on hold: оплаченная сумма отличается от итога заказа (фиксируется фактически оплаченная сумма), платёж поступил после отмены заказа, или тестовый платёж получен, пока магазин работает в боевом режиме (реальных денег нет, ничего не записывается). Примечание объясняет причину. Проверьте заказ, затем обработайте его или сделайте возврат платежа.

Payment error: ожидающий платёж не прошёл или был отменён.

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

Повторные или параллельные callback-запросы никогда не создают второй заказ и дублирующие примечания. Если оплачивается вторая попытка уже оплаченной корзины, заказ не меняется; примечание Duplicate payment просит вас вернуть эту оплату в панели мерчанта Paytrail.

Блок оплаты Paytrail

На странице заказа показан блок Paytrail payment с идентификатором транзакции, режимом (метка TEST mode для тестовых платежей), способом оплаты, статусом Paytrail, оплаченной и возвращённой суммой, формой возврата, историей возвратов, попытками оплаты корзины и Paytrail notes заказа.

Возвраты

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

Если способ оплаты не поддерживает прямые возвраты, модуль автоматически запускает возврат по e-mail: Paytrail отправляет покупателю письмо с просьбой указать банковский счёт. Для этого в заказе нужен e-mail покупателя. В примечании указано, какой вид возврата запущен.

Возврат может быть выполнен сразу или обработан позже. Последующее подтверждение от Paytrail добавляется примечанием. Если Paytrail не смог выполнить возврат, примечание сообщит, что деньги покупателю не возвращены, и возврат больше не считается выполненным; верните деньги покупателю другим способом. Если Paytrail сразу отклоняет возврат, блок показывает ошибку, и возврат не регистрируется. Полный возврат переводит заказ в статус Refunded. Частичный возврат статус не меняет.

Модуль не создаёт кредит-ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Paytrail. Возвраты, сделанные в панели мерчанта Paytrail, не синхронизируются обратно с PrestaShop.

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

Модуль работает с лицензионным ключом VibeFox с сайта vibefox.net. Блок лицензии License — VibeFox Paytrail Gateway — это первый блок на странице Modules > Module Manager > VibeFox Paytrail Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого в блоке отображаются ключ в маскированном виде, статус (например, дата, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-paytrail и ссылка 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.

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

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

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

Paytrail не появляется на оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено и либо Test mode включён, либо Merchant ID и Secret key заполнены (а не публичный тестовый аккаунт 375917). Проверьте, что валюта корзины — EUR. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя. На странице настроек показывается предупреждение при отсутствии учётных данных и неверной валюте магазина.

Платёж прошёл, но заказ не создан: callback не может достучаться до вашего магазина, а покупатель не вернулся в магазин. Callback URL из раздела Заказы должен быть доступен из интернета (без базовой аутентификации и без блокировки файрволом).

Callback или возврат отвечает Payment verification failed.: подпись недействительна, или платёж не относится к попытке оплаты этой корзины. Ничего не меняется. Проверьте, что Secret key верный и принадлежит Merchant ID.

Callback отвечает Temporarily unavailable: заказ в этот момент подтверждался другим запросом, или заказ не удалось создать (например, модуль отключён). Paytrail повторит вызов. Причину смотрите в поле Log.

Покупатель видит ошибку при выборе Paytrail: смотрите поле Log на странице модуля. Например, Paytrail API error (401) означает неверные учётные данные. Включите Debug log для подробностей.

Merchant ID не сохраняется: он должен содержать только цифры. Скопируйте его заново из панели мерчанта Paytrail.

Заказ в статусе Paytrail payment on hold: прочитайте примечания в блоке Paytrail payment. Причина — другая оплаченная сумма, платёж после отмены или тестовый платёж в боевом режиме.

Возврат не проходит: прочитайте сообщение. This order has no confirmed Paytrail payment. Refund it manually. означает, что нет подтверждённого платежа Paytrail для возврата. The live Paytrail credentials used for this payment are missing. Enter them in the Paytrail settings. означает, что платёж прошёл в боевом режиме, а боевые учётные данные не заданы. Invalid refund amount: at most … означает, что сумма больше остатка, доступного для возврата. Если способ оплаты поддерживает только возврат по e-mail, заказу нужен e-mail покупателя.

Хук для разработчиков: хук actionWcpPaytrailPaymentRequest изменяет запрос на оплату до подписи и отправки.

Удаление

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

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