VibeFox Paytrail for WooCommerce — Помощь

Требования

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

WooCommerce: 7.0 или новее, установлен и активен. Без него плагин откажется активироваться.

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

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

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

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

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

Установка

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

2. Нажмите Activate.

3. Откройте настройки: WooCommerce > Settings > Payments > Paytrail > Manage или нажмите Settings под названием плагина на странице плагинов.

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

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

6. Включите Enable/Disable и сохраните изменения.

Настройка

Все параметры собраны на одной странице: WooCommerce > Settings > Payments > Paytrail. Над полями настроек при включённом тестовом режиме отображается надпись Test mode is active.. В рабочем режиме плагин предупреждает, если отсутствуют Merchant ID или Secret key, а также если валюта магазина отличается от EUR. В обоих случаях Paytrail не показывается при оформлении заказа. В списке способов оплаты Paytrail помечается как требующий настройки, пока для рабочего режима не заданы учётные данные.

При сохранении Merchant ID, содержащий любые символы, кроме цифр, не сохраняется: отображается ошибка, а в поле остаётся прежнее значение.

General

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

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

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

API credentials

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

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

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

Secret key: ваш секретный ключ Paytrail. Используется, когда тестовый режим выключен.

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

Orders

В этом разделе показан URL для callback, который выглядит как https://your-site/wc-api/ptg_paytrail/. Paytrail подтверждает каждый платёж обращением между серверами по этому адресу. Он передаётся с каждым платежом, поэтому в панели Paytrail настраивать ничего не нужно, однако сайт должен быть доступен из интернета.

Order status after payment: статус оплаченного заказа. Статус устанавливается в один шаг, поэтому покупатель получает только один комплект писем.

Advanced

Debug log: Log API requests and callbacks. Записывается в журнал WooCommerce > Status > Logs, источник wcp_paytrail_gateway, без персональных данных и ключей. Ошибки записываются всегда. По умолчанию: выключено.

Delete data on uninstall: Delete settings, logs and Paytrail order data when the plugin is deleted. Деактивация плагина никогда ничего не удаляет. Без данных о транзакциях Paytrail возврат средств по старым заказам из WooCommerce станет невозможен. По умолчанию: выключено.

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

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

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

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

Если 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, не могут быть оплачены через Paytrail.

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

Способ оплаты работает на классической странице оформления, в блоке «Оформление заказа» и на странице Pay for order. Он совместим с высокопроизводительным хранилищем заказов WooCommerce (HPOS).

Покупатель выбирает конкретный метод на странице Paytrail, а не при оформлении заказа в вашем магазине. В плагине нет токенизации и сохранения карт, поддержки WooCommerce Subscriptions, схемы «магазин в магазине», ручной активации счетов и отчётов о взаиморасчётах.

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

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

Pending payment: платёж Paytrail создан, но покупатель ещё не оплатил его. В примечании к заказу указаны ID транзакции Paytrail, сумма и режим.

Processing or Completed: платёж подтверждён. Статус определяется настройкой Order status after payment. В примечании к заказу указаны транзакция, способ оплаты, использованный в Paytrail, и сумма. ID транзакции соответствует ID транзакции Paytrail.

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

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

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

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Paytrail (на кнопке отображается ваш Title). Поддерживаются полные и частичные возвраты только на сумму (без указания конкретных позиций). Кнопка доступна только для заказов с подтверждённым платежом Paytrail. Для возврата используются учётные данные того режима, в котором был сделан платёж, поэтому для реального платежа должны быть заданы рабочие реквизиты.

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

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

Возвраты, сделанные в панели Paytrail Merchant Panel, не синхронизируются обратно с WooCommerce.

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

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

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

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

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

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

Paytrail не появляется при оформлении заказа: убедитесь, что лицензия активна, опция Enable/Disable включена и либо активен Test mode, либо заполнены Merchant ID и Secret key. Проверьте, что валютой магазина (или валютой заказа на странице Pay for order) является EUR. На странице настроек для каждой из этих проблем выводится предупреждение.

Платёж прошёл, но заказ остаётся в статусе Pending payment: callback-запрос не может связаться с вашим сайтом, а покупатель не вернулся в магазин. URL для callback, указанный в разделе Orders, должен быть доступен из интернета (без режима обслуживания, базовой HTTP-аутентификации или блокирующего брандмауэра).

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

Платёж не создаётся: в примечании к заказу и в журнале выводится ошибка Paytrail, например Paytrail API error (401): … при неверных учётных данных. Включите Debug log и проверьте WooCommerce > Status > Logs, источник wcp_paytrail_gateway.

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

Заказ переведён в статус On hold: прочтите примечание к заказу. Причиной может быть ожидающий или отложенный платёж, несовпадение оплаченной суммы, платёж после отмены заказа или тестовый платёж в рабочем режиме.

Возврат не удаётся: прочтите сообщение. This order has no confirmed Paytrail payment. Refund it manually. означает отсутствие подтверждённого платежа Paytrail для возврата. Сообщение об отсутствии рабочих учётных данных говорит о том, что платёж совершён в рабочем режиме, а боевые реквизиты не заданы. Если способ оплаты поддерживает только возврат по e-mail, у заказа должен быть заполнен адрес электронной почты плательщика.

Хуки для разработчиков: фильтр ptg_payment_request позволяет изменить параметры запроса к платежу до его подписания и отправки; фильтр ptg_icon изменяет иконку при оформлении заказа.

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

Удаление

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

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