VibeFox Przelewy24 for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

Валюта: корзина должна быть в PLN, EUR, GBP или CZK. В других валютах способ оплаты скрыт на странице оформления заказа. Корзина списывается в её собственной валюте; модуль не конвертирует валюты.

Учётная запись Przelewy24: нужна учётная запись мерчанта Przelewy24 и её данные API: Merchant ID, API-ключ (в панели Przelewy24 называется report key), CRC-ключ и, если у вашего магазина есть собственный ID, POS ID (Shop ID). Их можно найти в панели мерчанта Przelewy24 на panel.przelewy24.pl в разделе My data > API data and configuration. Ключи sandbox берутся из отдельной учётной записи sandbox на sandbox.przelewy24.pl/panel. Больше ничего в панели Przelewy24 настраивать не нужно: модуль передаёт свой URL уведомления с каждым платежом. Магазин должен быть доступен из интернета, потому что Przelewy24 отправляет на него уведомления об оплате.

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

Установка

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

2. По завершении загрузки нажмите Configure или позже найдите VibeFox Przelewy24 Payment в списке модулей и нажмите Configure.

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

4. Введите ключи sandbox (Merchant ID, API-ключ, CRC-ключ; POS ID — только если он отличается от Merchant ID), включите Enable/Disable, нажмите Save и выполните тестовый платёж в режиме sandbox.

5. Введите рабочие ключи, выключите Test Mode и нажмите Save, чтобы принимать реальные платежи.

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Przelewy24 Payment > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница показывает предупреждения, если чего-то не хватает. Пока включён sandbox: Sandbox (test) mode is on: payments go to the Przelewy24 sandbox and no real money is charged. Do not ship orders paid in test mode. Когда ключи текущего режима неполные: Enter the Sandbox Merchant ID, API key and CRC key - until then Przelewy24 is not shown at checkout. (или то же для рабочих ключей Live). Если Przelewy24 не принимает валюту по умолчанию вашего магазина, предупреждение называет эту валюту и поддерживаемые валюты. После сохранения предупреждения сразу отражают новый режим и новые ключи. Пробелы и переносы строк, скопированные вместе с ключами из панели Przelewy24, удаляются при сохранении.

Przelewy24

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

Title: название способа оплаты, которое видят покупатели на странице оформления заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: Przelewy24. Обязательное поле: при сохранении с пустым названием появится Enter a title for the payment method.

Description: текст под способом оплаты на странице оформления заказа. По умолчанию: Pay with BLIK, online bank transfer or card via Przelewy24.

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

В этом разделе объясняется, где найти ключи (My data > API data and configuration в панели мерчанта Przelewy24), и даны ссылки на panel.przelewy24.pl и sandbox.przelewy24.pl/panel.

Test Mode: использует sandbox Przelewy24 (sandbox.przelewy24.pl) и ключи Sandbox. Реальные деньги не списываются. Выключите, чтобы принимать реальные платежи на secure.przelewy24.pl рабочими ключами Live. По умолчанию: включено. Пока режим включён, покупатели видят Sandbox mode - no real money is charged под способом оплаты.

Рабочие ключи (Live)

Live Merchant ID: ваш ID мерчанта Przelewy24, только цифры.

Live POS ID (optional): Shop ID (posId). Оставьте пустым, если он совпадает с Merchant ID.

Live API key (report key): API-ключ из панели Przelewy24. Используется для аутентификации в API.

Live CRC key: используется для подписи запросов к Przelewy24 и для проверки подписи уведомлений Przelewy24.

Ключи sandbox

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

Sandbox POS ID (optional): Shop ID (posId) учётной записи sandbox. Оставьте пустым, если он совпадает с Merchant ID.

Sandbox API key (report key): API-ключ учётной записи sandbox.

Sandbox CRC key: CRC-ключ учётной записи sandbox, используется для подписи запросов и проверки уведомлений sandbox.

Сохранённые API-ключи и CRC-ключи больше никогда не показываются. Поле остаётся пустым и показывает Saved - leave empty to keep it. Вводите новое значение, только если хотите его изменить.

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

Рабочие и sandbox-ключи различаются. Merchant ID и POS ID должны содержать только цифры; пока не введены Merchant ID, API-ключ и CRC-ключ текущего режима, способ оплаты не показывается на странице оформления заказа. Платёж, начатый в одном режиме, всегда проверяется и возвращается ключами этого режима, даже после переключения, поэтому сохраняйте ключи прежнего режима, пока его платежи открыты или могут быть возвращены.

Уведомления об оплате

Notification URL: адрес, на который Przelewy24 отправляет уведомления об оплате. При включённых ЧПУ он выглядит так: https://your-shop/module/wcp_przelewy24_payment/notify, возможно, с кодом языка, например /en/. Модуль передаёт этот URL в Przelewy24 с каждым платежом и каждым возвратом, поэтому в панели Przelewy24 ничего настраивать не нужно. URL должен быть доступен из интернета: перед ним не должно быть брандмауэра или HTTP-аутентификации. Он продолжает работать, пока магазин находится в режиме обслуживания, и не блокируется ограничением по стране для вашего магазина. Без уведомлений платёж всё равно подтверждается, когда покупатель возвращается в магазин (см. Оформление заказа); если покупатель не вернулся, заказ не создаётся.

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

Debug Log: записывает технические события (номера корзин, ID транзакций P24, ошибки) в logs/wc_p24_debug.log.php в папке модуля. Файл нельзя открыть из веба. Ошибки и предупреждения, например отклонённые уведомления или неудачная проверка или возврат, всегда записываются; включите переключатель, чтобы записывать и каждый шаг. Ключи, тела запросов и персональные данные никогда не записываются. По умолчанию: выключено.

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

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

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

На шаге оплаты покупатель выбирает способ оплаты (по умолчанию Przelewy24 с логотипом P24) и подтверждает заказ. Модуль регистрирует в Przelewy24 транзакцию на сумму корзины в валюте корзины, с e-mail, именем и страной выставления счёта покупателя и описанием Cart # с номером корзины и названием вашего магазина. Каждая попытка оплаты получает свой ID сессии. Покупатель переходит на страницу оплаты Przelewy24 и платит через BLIK, онлайн-перевод, банковскую карту или другой способ, включённый для вашего аккаунта Przelewy24. Страница оплаты открывается на языке корзины покупателя, если его поддерживает Przelewy24, иначе на английском. На этом этапе заказа ещё не существует.

Заказ отмечается оплаченным только после подтверждения Przelewy24. Przelewy24 присылает вашему магазину подписанное уведомление. Модуль проверяет подпись CRC-ключом, Merchant ID и POS ID, то, что сессия была зарегистрирована для этой корзины и в том же режиме, а также то, что сумма и валюта совпадают с попыткой оплаты и текущей суммой корзины. Только после этого он проверяет транзакцию в Przelewy24 (Przelewy24 зачисляет только проверенные платежи) и создаёт заказ со статусом Payment accepted. Вебхуки без действительной подписи отклоняются.

После оплаты покупатель возвращается в ваш магазин. Если уведомление ещё не пришло, модуль запрашивает у Przelewy24 статус транзакции аутентифицированным запросом сервер-сервер (не чаще одного раза в 10 секунд на корзину) и применяет те же проверки. Сама страница возврата никогда не отмечает заказ оплаченным. Когда оплата подтверждена, покупатель видит стандартную страницу подтверждения заказа. Пока оплата не подтверждена, страница Payment confirmation показывает We have not received the payment confirmation from Przelewy24 yet. If you have paid, it will be confirmed in a few minutes. If the payment was interrupted, you can try again: с кнопкой Check again и кнопкой Pay again, которая открывает оформление заказа. Корзина сохраняется, а платёж, сделанный позже по старой странице Przelewy24 той же корзины, по-прежнему принимается. Если заказ на удержании, страница подтверждения показывает Your payment is being verified. We will send you an e-mail as soon as it is confirmed.

Если платёж не удаётся начать, покупатель остаётся на странице оформления заказа с коротким сообщением: Payment error: Przelewy24 could not start the payment. Please try again or choose another payment method. (причина записывается в журнал), Payment gateway is not configured properly. Please contact the administrator. (не хватает ключей текущего режима), сообщение о том, что Przelewy24 не может принимать платежи в валюте корзины, или The order total must be greater than zero. Корзина, для которой уже есть заказ, повторно в Przelewy24 не отправляется; покупатель переходит к подтверждению заказа.

В модуле нет сохранённых карт и оплаты в один клик, подписок и регулярных платежей, нет выбора способа оплаты P24 (например, поля для кода BLIK) на странице оформления заказа, нет виджетов рассрочки, и содержимое корзины в Przelewy24 не передаётся.

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

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

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

Payment accepted: платёж проверен. Он записывается с номером заказа P24 в качестве ID транзакции, а заметка показывает номер заказа P24, сумму и режим. Каждый платёж применяется один раз.

Przelewy24 payment on hold: сумма или валюта, сообщённые Przelewy24, отличаются от корзины (например, корзину изменили после начала оплаты); платёж не подтверждён, и об этом говорится в заметке. Или платёж поступил и был проверен для заказа, который был отменён; заказ не открывается заново молча, заметка предлагает отправить его или вернуть платёж. Проверьте платёж в панели Przelewy24. Если после расхождения для заказа на удержании придёт корректный платёж по другой попытке, заказ перейдёт в статус Payment accepted.

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

Если второй платёж поступает для корзины, заказ по которой уже оплачен или возвращён (старая ссылка на оплату, две вкладки браузера), он не подтверждается, поэтому Przelewy24 его не зачисляет. Заметка к заказу просит проверить его в панели Przelewy24 и при необходимости вернуть покупателю.

Блок оплаты Przelewy24

На странице заказа показан блок Przelewy24 payment с номером заказа P24, сессией, средой (значок Sandbox для платежей sandbox), статусом платежа и способом проверки (уведомление или возврат), суммами оплаты и возвратов, формой возврата, историей возвратов и Payment notes заказа.

Возвраты

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

Przelewy24 обрабатывает возвраты асинхронно. Блок показывает Refund of … requested at Przelewy24. The result will be added as an order note., в истории возвратов появляется статус requested, и добавляется заметка. Результат приходит позже на URL уведомления: статус становится completed с заметкой Przelewy24: refund of … completed. или rejected с заметкой о том, что деньги покупателю не возвращены. Полный возврат переводит заказ в статус Refunded в момент запроса; частичный возврат статус не меняет. Если возврат отклонён, проверьте его в панели Przelewy24; статус заказа автоматически не возвращается.

Если Przelewy24 не принимает запрос на возврат, блок показывает Przelewy24 refund failed: с причиной, и возврат не регистрируется. Модуль не создаёт кредит-ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Przelewy24, а возвраты, сделанные напрямую в панели Przelewy24, в заказ не добавляются.

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

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

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

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

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

Przelewy24 не появляется на странице оформления заказа: проверьте, что лицензия активна, Enable/Disable включено, введены Merchant ID, API-ключ и CRC-ключ текущего режима (ключи Sandbox, пока включён Test Mode, иначе ключи Live; Merchant ID и POS ID — только цифры), а валюта корзины — PLN, EUR, GBP или CZK. Предупреждения вверху настроек называют проблему. В разделе Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя. Разработчики могут изменить список валют с помощью хука actionWcpPrzelewy24SupportedCurrencies (только валюты с двумя знаками после запятой, включённые для вашей учётной записи Przelewy24).

Платёж прошёл, но заказ не создан: уведомление Przelewy24 не дошло до магазина, и покупатель не вернулся в магазин. Проверьте, что Notification URL доступен из интернета (перед ним нет брандмауэра и HTTP-аутентификации), и что Merchant ID, POS ID и CRC-ключ режима платежа верны. Отклонённые уведомления записываются в журнал даже при выключенном Debug Log; смотрите поле Log на странице модуля.

Как магазин отвечает на уведомления: обработанное, повторное или неизвестное уведомление получает ответ HTTP 200. В остальных случаях Przelewy24 отправит его позже: 400 (отсутствуют или некорректны данные), 401 Invalid signature (неверный CRC-ключ, другой Merchant ID или POS ID), 401 Invalid signature for this payment (уведомление подписано ключами другого режима, чем у платежа), 405 (не POST-запрос), 500 Verification failed (проверка в Przelewy24 не прошла; заметка добавляется к заказу один раз, если он существует), 500 Order could not be created (например, модуль отключён; следующее уведомление создаст заказ без повторной проверки) и 503 Busy, retry later (корзину в тот же момент подтверждал другой запрос).

Покупатель видит Payment error: Przelewy24 could not start the payment: Przelewy24 отклонил транзакцию, обычно из-за неверных ключей текущего режима (ключи sandbox работают только в режиме sandbox, рабочие ключи Live — только в рабочем режиме). Ошибка Przelewy24 записана в журнал.

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

Возврат не проходит: This order has no verified Przelewy24 payment. Cannot process refund. означает, что заказ не оплачен проверенным платежом Przelewy24. The payment was made in the Przelewy24 sandbox, but the Sandbox keys are missing. (или то же для Live) означает, что ключи режима платежа были удалены; введите их снова. Invalid refund amount означает, что сумма пустая, не является числом или больше суммы, которая ещё не возвращена.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Przelewy24 Payment и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete data on uninstall включено, настройки модуля и журнал удаляются. Если выключено, все настройки сохраняются для повторной установки. Данные об оплате Przelewy24 по заказам (сессии, номера заказов P24, возвраты) и статус заказа Przelewy24 payment on hold всегда сохраняются, поэтому заказы, оплаченные ранее, можно вернуть и после повторной установки. Существующие заказы сохраняют свои заметки об оплате и ID транзакций.

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