VibeFox Mollie for PrestaShop — Допомога

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта магазину: валюта кошика має бути однією з валют, які підтримує Mollie: AED, AUD, BGN, BRL, CAD, CHF, CZK, DKK, EUR, GBP, HKD, HUF, ILS, ISK, JPY, MXN, MYR, NOK, NZD, PHP, PLN, RON, SEK, SGD, THB, TWD, USD, ZAR. Для інших валют варіант оплати приховується в оформленні замовлення. Які способи оплати пропонує Mollie, залежить від валюти та вашого облікового запису.

Доступ до магазину з інтернету: Mollie надсилає вебхуки до вашого магазину, тож сайт має бути доступним з інтернету. Без вебхуків замовлення все одно створюються, коли покупець повертається з Mollie.

Обліковий запис Mollie: потрібні API-ключі з Mollie Dashboard > Developers > API keys. Тестові ключі починаються з test_, робочі — з live_. Інші ключі чи секрети не потрібні. Самі способи оплати вмикаються у вашому обліковому записі Mollie.

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

Встановлення

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

2. Коли завантаження завершиться, натисніть Configure або пізніше знайдіть VibeFox Mollie Gateway у списку модулів і натисніть Configure.

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

4. Введіть тестові та робочі API-ключі (див. Налаштування). У Mollie вебхук налаштовувати не потрібно.

5. Увімкніть Enable/Disable і натисніть Save. Залиште Test Mode увімкненим, доки не здійсните тестовий платіж, а потім вимкніть його.

Під час встановлення модуль створює два статуси замовлення: Awaiting Mollie payment і Mollie payment on hold. PrestaShop пропонує новий платіжний модуль для всіх валют, країн і груп клієнтів. Обмежити їх можна в Payment > Preferences.

Налаштування

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Mollie Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, коли Mollie увімкнено, але API-ключ поточного режиму порожній, і коли Mollie не підтримує валюту за замовчуванням магазину. В обох випадках варіант оплати приховується в оформленні замовлення.

Під час збереження API-ключ, який не починається з test_ або live_ із подальшими щонайменше 30 літерами та цифрами, не зберігається: з'являється помилка, а раніше збережений ключ залишається.

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

Enable/Disable: Enable Mollie Gateway вмикає або вимикає варіант оплати. За замовчуванням: off.

Title: назва способу оплати, яка показується покупцеві в оформленні замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Mollie. Обов'язкове поле.

Description: опис способу оплати, який показується покупцеві в оформленні замовлення. За замовчуванням: Pay securely via Mollie.

API-ключі

Свої API-ключі можна знайти в Mollie Dashboard у розділі Developers > API keys; у цьому розділі є посилання на цю сторінку. Тестові та робочі ключі окремі.

Test Mode: використовує тестовий API-ключ для нових платежів. Реальні платежі не обробляються. На тестовій сторінці оплати Mollie можна вибрати результат платежу. Покупці бачать під варіантом оплати напис Test mode: no real payment will be made. Платежі, створені в іншому режимі, для перевірки статусів і повернень продовжують використовувати ключ свого режиму. За замовчуванням: on.

Test API Key: ваш тестовий API-ключ Mollie (починається з test_).

Live API Key: ваш робочий API-ключ Mollie (починається з live_).

Збережені ключі більше ніколи не відображаються. Поле залишається порожнім і показує Saved — leave empty to keep it. Вводьте нове значення, лише якщо хочете його змінити.

Clear saved keys: позначте ключ і натисніть Save, щоб видалити його. Порожнє поле зберігає збережене значення.

Webhook: показує URL вебхука. Налаштовувати нічого не потрібно: модуль передає цю URL до Mollie з кожним платежем. З дружніми URL вона виглядає так: https://your-shop/module/wcp_mollie_gateway/webhook, можливо, з кодом мови. Вона має бути доступною з інтернету, інакше замовлення створюються лише тоді, коли покупець повертається з Mollie.

Замовлення

Order Status After Payment: статус замовлення, який встановлюється після успішної оплати. Статус встановлюється одним кроком.

Банківські перекази очікують у статусі Awaiting Mollie payment. Авторизовані платежі та невідповідності суми або валюти переходять у статус Mollie payment on hold.

Додатково

Logging: записує виклики API та вебхуки до logs/molg_debug.log.php у папці модуля. Файл не можна відкрити з веб. Помилки та попередження завжди записуються, навіть коли опцію вимкнено. API-ключі та дані покупців ніколи не записуються. За замовчуванням: off.

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

Delete Data on Uninstall: коли увімкнено, налаштування модуля та його журнал видаляються під час видалення модуля. Ідентифікатори платежів Mollie, збережені із замовленнями, записи про повернення та статуси замовлень модуля завжди зберігаються. За замовчуванням: off.

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

На етапі оплати покупець обирає варіант оплати (за замовчуванням Mollie) і підтверджує. Модуль створює платіж Mollie на суму кошика у валюті кошика (JPY та ISK без десяткових знаків) з описом Order # і номером кошика та надсилає покупця на розміщену сторінку оплати Mollie. Там покупець обирає один із способів оплати, увімкнених у вашому обліковому записі Mollie, і сплачує. На цьому етапі замовлення ще не існує.

Вебхуки Mollie не підписані й містять лише ID платежу. Тому модуль ніколи не довіряє вебхуку як такому: він приймає лише ID платежів, які створив сам, зчитує платіж з API Mollie ключем того режиму, в якому платіж було проведено, перевіряє, що платіж належить кошику, і порівнює сплачену суму та валюту із сумою кошика. Замовлення позначається оплаченим лише після того, як Mollie підтвердить це таким способом. Модуль обробляє такі статуси платежів Mollie:

Коли покупець повертається, модуль так само перевіряє останній платіж кошика через API Mollie. Проведений платіж веде на стандартну сторінку підтвердження замовлення з написом Your payment with Mollie has been received. Для банківського переказу сторінка показує Your order will be processed as soon as Mollie receives your bank transfer. Якщо замовлення на утриманні, сторінка показує We are confirming your payment with Mollie. The order will be updated automatically — please do not pay again. Якщо платіж існуючого замовлення не вдався або замовлення скасовано, сторінка показує Your Mollie payment was not completed. Please contact us about this order.

Якщо платіж було скасовано, він не вдався, закінчився строк або не завершено, покупець повертається до оформлення замовлення з повідомленням, наприклад You cancelled the Mollie payment. You can try again or choose another payment method. або The Mollie payment has expired. Please try again or choose another payment method. Кошик зберігається. Якщо Mollie недоступна або ще не ухвалила рішення, з'являється сторінка Payment confirmation, яка просить покупця не платити знову та пропонує кнопку Check again; вебхук створить замовлення, щойно прийде.

Коли покупець платить знову, відкритий платіж Mollie на ту саму суму використовується повторно, а не створюється другий платіж до оплати. Якщо сума кошика змінилася, старий відкритий платіж скасовується в Mollie, коли Mollie це дозволяє. Якщо старий платіж тим часом сплачено, замовлення створюється без нового платежу.

Якщо Mollie не може почати платіж, покупець залишається в оформленні замовлення з коротким повідомленням, наприклад The payment provider could not be reached. Please try again in a moment., This payment method is temporarily unavailable. Please choose another payment method. (невірний API-ключ) або Mollie cannot accept a payment of this amount or currency. Please choose another payment method. Технічна причина записується в журнал.

Вебхук працює, поки магазин у режимі обслуговування, і не блокується обмеженням за країнами вашого магазину.

Спосіб Mollie покупець обирає на сторінці Mollie, а не в оформленні замовлення вашого магазину. Модуль не підтримує підписки та регулярні платежі, збережені картки чи мандати, поля для картки на вашому сайті, кнопки експрес-оплати Apple Pay чи PayPal і не використовує Orders API, тож Mollie не пропонує для таких платежів способи, яким потрібні рядки замовлення (наприклад, деякі варіанти Klarna, Billie або in3). Авторизовані платежі захоплюються або анулюються в Mollie Dashboard, а не в PrestaShop.

Замовлення та повернення коштів

Статуси замовлення

Замовлення ще немає: покупця відправлено до Mollie, і він не сплатив, або Mollie ще не підтвердила платіж. Існує лише кошик.

Payment accepted або Delivered: платіж підтверджено. Статус відповідає Order Status After Payment. Платіж записується з ID платежу Mollie (tr_...) як ID транзакції, а примітка показує платіж Mollie, спосіб оплати та режим.

Awaiting Mollie payment: покупець обрав банківський переказ на сторінці Mollie. Замовлення переходить у оплачений статус, коли Mollie отримує кошти.

Mollie payment on hold: авторизований платіж очікує захоплення; Mollie повідомила про чарджбек; сплачена сума або валюта відрізняються від кошика (наприклад, кошик змінили після початку платежу); тестовий платіж було сплачено, поки магазин працював у робочому режимі (кошти не надійшли); або платіж надійшов після скасування замовлення. Примітка пояснює причину. Перевірте платіж у Mollie Dashboard, а потім опрацюйте замовлення або поверніть платіж.

Payment error: банківський переказ або авторизація існуючого замовлення не вдалися, закінчився строк або їх скасовано. Оплачене замовлення ніколи не змінюється.

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

Якщо сплачено другий платіж за тим самим кошиком, замовлення не змінюється. Примітка просить вас повернути дубльований платіж у Mollie Dashboard.

Блок Mollie payment

На сторінці замовлення показано блок Mollie payment з ID платежу Mollie, способом оплати, статусом платежу, сплаченою та поверненою сумою, позначкою Test mode для тестових платежів, історією повернень і Mollie notes замовлення. Примітки видно лише в бек-офісі.

Повернення коштів

У блоці Mollie payment введіть суму (підставляється сума, яку ще не повернуто), за бажанням причину, і натисніть Refund via Mollie. Підтвердіть запитання Refund this amount through Mollie? This cannot be undone. Підтримуються повні та часткові повернення. Вам потрібне право редагувати замовлення; доступ до сторінок модулів не потрібен. Повернення здійснюються на суму та у валюті, які списала Mollie, тож після розбіжності суми можна повернути не більше, ніж фактично сплатив покупець, а не суму замовлення. Повернення надсилається для платежу, який фактично оплатив замовлення, з API-ключем режиму, в якому його було проведено, тому цей ключ має бути заданий. Якщо Mollie відхиляє повернення, блок показує повідомлення про помилку від Mollie, і повернення не записується. Успішне повернення додається до історії повернень і приміток з ID повернення Mollie. Повне повернення переводить замовлення в статус Refunded. Часткове повернення статус не змінює. Повернення доступні, щойно Mollie повідомила, що платіж оплачено.

Модуль не створює кредитні накладні (credit slips). Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають кошти через Mollie. Повернення, створені в Mollie Dashboard, на замовленні не відображаються; чарджбек додає примітку.

Ліцензійний ключ

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

Без активного ключа Mollie покупцям в оформленні замовлення не показується. Якщо платіж усе ж розпочато, покупець бачить This payment method is not available. Please choose another one. Вітрина PrestaShop не знає, що ви увійшли в бек-офіс, тому спосіб оплати приховано і для вас: налаштувати модуль можна до купівлі ключа, але перевірити його в оформленні замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Існуючі замовлення не зачіпаються: платежі, які вже розпочато, усе одно підтверджуються, а повернення працюють.

Коли ліцензія спливає, модуль продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову, поки ви працюєте в бек-офісі: раз на день протягом перших 14 днів після введення ключа, потім раз на тиждень. Cron-завдання не потрібне. Видалення або скидання модуля завжди видаляє ліцензійний ключ і статус ліцензії.

Усунення несправностей

Mollie не відображається в оформленні замовлення: перевірте, що ліцензія активна, Enable/Disable увімкнено і в поточному режимі є API-ключ: Test API Key у тестовому режимі, Live API Key у робочому. Перевірте, що валюта кошика підтримується Mollie. Сторінка налаштувань показує попередження про відсутній ключ і про непідтримувану валюту магазину. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: вебхук не може достукатися до вашого магазину. URL, який показано в Webhook, має бути доступним з інтернету (без базової автентифікації та без брандмауера, що її блокує). Замовлення також створюється, коли покупець повертається до магазину після оплати або натискає Check again.

Вебхук відповідає Unknown payment.: платіж створено не цим магазином або Mollie не знає його з API-ключем свого режиму, наприклад платіж з іншого облікового запису Mollie.

Вебхук відповідає Payment ID mismatch.: платіж не належить кошику, для якого його створено. Нічого не змінюється.

Вебхук відповідає Failed to fetch payment.: API Mollie недоступний, або API-ключ режиму платежу не задано. Mollie повторить вебхук пізніше.

Вебхук відповідає Temporarily unavailable.: кошик у цей момент обробляв інший запит, або замовлення не вдалося створити (наприклад, модуль вимкнено). Mollie повторить вебхук. Увімкніть Logging, щоб побачити причину.

URL вебхука в браузері показує Method not allowed.: це нормально. URL приймає лише запити від Mollie.

API-ключ не зберігається: ключ має починатися з test_ або live_ з подальшими щонайменше 30 літерами та цифрами. Скопіюйте його ще раз з Mollie Dashboard.

Покупець бачить помилку під час вибору Mollie: перегляньте поле Log на сторінці модуля. Там показано HTTP-код і повідомлення Mollie. 401 означає невірний API-ключ; 422 вказує на поле запиту, наприклад суму або валюту, які Mollie не приймає.

Замовлення в статусі Mollie payment on hold: прочитайте примітки замовлення (див. Статуси замовлення), а потім опрацюйте замовлення або поверніть платіж.

Повернення не проходить із повідомленням про режим: платіж було проведено в тестовому або робочому режимі, а API-ключ цього режиму не задано. Введіть його і спробуйте ще раз.

Інші валюти або дані платежу: розробники можуть змінити список валют хуком actionWcpMollieSupportedCurrencies, а запит на оплату — хуком actionWcpMolliePaymentData.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Mollie Gateway і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete Data on Uninstall увімкнено, налаштування модуля та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для повторного встановлення. Ідентифікатори платежів і записи про повернення Mollie та статуси замовлень Awaiting Mollie payment і Mollie payment on hold завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Існуючі замовлення зберігають свої платіжні примітки та ID транзакцій.

Mollie є товарним знаком її власника. Цей модуль не пов'язаний із Mollie і не схвалений нею.