VibeFox Przelewy24 for WooCommerce — Помощь

Требования

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

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

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

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

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

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

Установка

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

2. Нажмите Activate.

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

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

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

6. Введите рабочие ключи (Live), снимите отметку Test Mode и сохраните, чтобы принимать настоящие платежи.

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > Przelewy24. Над полями страница показывает предупреждения, если чего-то не хватает. Пока включён 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. (или то же для рабочих ключей). Если Przelewy24 не принимает валюту магазина, предупреждение называет эту валюту и поддерживаемые валюты. После сохранения предупреждения сразу отражают новый режим и ключи. Пробелы и переносы строк, скопированные вместе с ключами из панели Przelewy24, удаляются при сохранении.

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

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

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

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: Enable sandbox (test) mode. Когда режим включён, новые платежи идут в sandbox Przelewy24 (sandbox.przelewy24.pl) с ключами sandbox, и реальные деньги не списываются. Снимите отметку, чтобы принимать настоящие платежи на secure.przelewy24.pl с рабочими ключами. По умолчанию: включено.

Рабочие ключи

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

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

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

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

Ключи sandbox

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

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

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

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

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

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

Этот раздел показывает URL уведомлений вашего магазина. Он выглядит так: https://your-site/wc-api/wc_p24_payment/. Плагин передаёт этот URL в Przelewy24 с каждым платежом, поэтому в панели Przelewy24 ничего настраивать не нужно. По тому же URL приходят результаты возвратов. URL должен быть доступен из интернета: без брандмауэра, режима обслуживания и HTTP-аутентификации перед ним. Без уведомлений платёж всё равно подтверждается, когда покупатель возвращается на страницу «Заказ получен» (см. Оформление заказа); если покупатель не возвращается, заказ остаётся в статусе «Ожидает оплаты».

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

Debug Log: Enable logging записывает технические события (номера заказов, ID транзакций P24, ошибки) в WooCommerce > Status > Logs, источник wcp_przelewy24_payment. Ошибки и предупреждения записываются всегда. Ключи, тела запросов и персональные данные никогда не записываются. По умолчанию: выключено.

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

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

Покупатель выбирает способ оплаты (по умолчанию Przelewy24, с логотипом P24 в блоке «Оформление заказа») и оформляет заказ. В режиме sandbox блок оформления заказа показывает Sandbox mode — no real money is charged. Плагин регистрирует транзакцию Przelewy24 на сумму заказа в валюте заказа с e-mail, именем и страной оплаты покупателя и добавляет к заказу заметку с ID сессии и режимом (sandbox или live). Каждая попытка оплаты получает свой ID сессии. Покупатель переходит на страницу оплаты Przelewy24 и платит через BLIK, онлайн-перевод, банковскую карту или другой способ, включённый для вашего аккаунта Przelewy24. Страница оплаты открывается на языке сайта, если его поддерживает Przelewy24, иначе на английском.

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

После оплаты покупатель возвращается на страницу «Заказ получен». Если уведомление ещё не пришло, плагин запрашивает статус транзакции у Przelewy24 аутентифицированным запросом сервер-сервер (не чаще одного раза в 10 секунд на заказ) и применяет те же проверки. Сама страница возврата никогда не отмечает заказ оплаченным. Пока оплата не подтверждена, страница показывает 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: с кнопкой Pay again, которая открывает страницу Pay for order. Если заказ на удержании, страница показывает Your payment is being verified. We will send you an e-mail as soon as it is confirmed. Платёж, сделанный позже по более старой странице Przelewy24 того же заказа, по-прежнему принимается.

Если оплату не удаётся начать, покупатель видит короткое сообщение: 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 не отправляется (This order does not need a payment any more.).

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

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

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

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

Pending payment: покупатель отправлен в Przelewy24 и ещё не заплатил, либо оплата ещё не подтверждена.

Processing or Completed: оплата проверена. WooCommerce ставит статус «В обработке», а для заказов только с виртуальными загружаемыми товарами — «Выполнен». В заметке к заказу указаны ID заказа P24, сумма и режим. ID транзакции заказа — это ID заказа P24. Каждый платёж применяется один раз.

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

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

Возвраты

Откройте заказ, нажмите Refund, введите сумму и нажмите Refund via Przelewy24. Поддерживаются полные и частичные возвраты. Возврат отправляется в том режиме, в котором был совершён платёж (sandbox или live), поэтому должны быть заполнены ключи этого режима. Przelewy24 обрабатывает возвраты асинхронно: сначала заметка к заказу сообщает, что возврат запрошен, а результат позже приходит на URL уведомлений и добавляется как заметка: Przelewy24: refund of … completed. или заметка об отклонении возврата, при котором деньги не были возвращены. Если возврат отклонён, проверьте его в панели Przelewy24; возврат WooCommerce, уже записанный к заказу, автоматически не удаляется.

Если Przelewy24 не принимает запрос на возврат, WooCommerce показывает Przelewy24 refund failed: с причиной, и возврат не записывается. Возвраты, сделанные непосредственно в панели Przelewy24, к заказу не добавляются.

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

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

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

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

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

Решение проблем

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

Оплата прошла, но заказ остаётся в статусе Pending payment: уведомление Przelewy24 не дошло до магазина, а покупатель не вернулся на страницу «Заказ получен». Проверьте, что URL из раздела Payment notifications доступен из интернета (нет режима обслуживания, брандмауэра или HTTP-аутентификации перед /wc-api/wc_p24_payment/), и что Merchant ID, POS ID и CRC-ключ режима платежа указаны верно. Отклонённые уведомления записываются в WooCommerce > Status > Logs, источник wcp_przelewy24_payment, даже когда Debug Log выключен.

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

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

Заказ On hold после оплаты: прочитайте заметку к заказу. Сумма или валюта отличались от заказа, либо платёж пришёл за отменённый заказ. Проверьте платёж в панели 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. (или то же для рабочих ключей) означает, что ключи режима платежа были удалены; введите их заново.

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

Удаление

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

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