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 на 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 вашого облікового запису 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.

Робочі ключі та ключі 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 у блоці Checkout) і оформлює замовлення. У режимі sandbox блок Checkout показує 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.).

Спосіб оплати працює в класичному оформленні замовлення, в блоці Checkout і на сторінці 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.