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-ключ і, якщо у вашого магазину є власний ідентифікатор, 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: ваш ідентифікатор мерчанта 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 надсилає сповіщення про платежі. За увімкнених зрозумілих URL вона має вигляд https://your-shop/module/wcp_przelewy24_payment/notify, можливо з кодом мови, наприклад /en/. Модуль передає цей URL у Przelewy24 з кожним платежем і кожним поверненням, тож у панелі Przelewy24 нічого налаштовувати не потрібно. URL має бути доступним з інтернету: перед ним не повинно бути брандмауера чи HTTP-автентифікації. Він продовжує працювати, поки магазин у режимі обслуговування, і не блокується обмеженням за країною для вашого магазину. Без сповіщень платіж усе одно підтверджується, коли покупець повертається в магазин (див. Оформлення замовлення); якщо покупець не повернувся, замовлення не створюється.

Додатково

Debug Log: записує технічні події (номери кошиків, ідентифікатори транзакцій P24, помилки) у logs/wc_p24_debug.log.php у папці модуля. Файл не можна відкрити з веб-браузера. Помилки та попередження, наприклад відхилені сповіщення або невдала перевірка чи повернення, завжди фіксуються; увімкніть перемикач, щоб фіксувати також кожен крок. Ключі, тіла запитів і персональні дані ніколи не фіксуються. За замовчуванням: вимкнено.

Log: показує розмір і останні записи журналу. Натисніть Clear log, щоб його очистити.

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

Оформлення замовлення

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

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

Після оплати покупець повертається у ваш магазин. Якщо сповіщення ще не надійшло, модуль запитує в 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 як ідентифікатором транзакції, а нотатка показує номер замовлення 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 або live), тож мають бути налаштовані ключі цього режиму. Повернення доступні після того, як 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 завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Існуючі замовлення зберігають свої нотатки про оплату та ідентифікатори транзакцій.

Przelewy24 — торговельна марка її власника. Цей модуль не пов’язаний із Przelewy24 і не схвалений Przelewy24.