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

Вимоги

OpenCart: 3.0.x (перевірено на 3.0.5.0) або 4.0.2 і новіші версії (перевірено на 4.1.0.3).

PHP: 8.0 або новіша версія.

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

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

Завантаження — це один zip-файл із пакетами для обох версій OpenCart. Розпакуйте його на своєму комп’ютері. Він містить README.txt, пакет для OpenCart 3 wcp_mollie_gateway-oc3-(version).ocmod.zip і пакет для OpenCart 4 wcp_mollie_gateway.ocmod.zip. Встановлюйте лише пакет для вашої версії OpenCart. Ліцензійний ключ однаковий для обох версій.

OpenCart 3

1. В адмінпанелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_mollie_gateway-oc3-(version).ocmod.zip. Розширення не містить модифікацій OCMOD, тож оновлювати Extensions > Modifications не потрібно. Замість інсталятора ви також можете скопіювати вміст папки upload цього пакета в кореневу папку вашого магазину.

2. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox Mollie Gateway і натисніть Install (зелена кнопка +). Вашому адміністратору потрібне право змінювати список платіжних розширень.

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

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

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

OpenCart 4

1. В адмінпанелі перейдіть до Extensions > Installer, натисніть Upload і виберіть файл wcp_mollie_gateway.ocmod.zip. Не перейменовуйте файл: OpenCart 4 бере код розширення з імені файлу, а перейменований пакет не працює.

2. Пакет з’явиться у списку встановлених розширень на тій самій сторінці. Натисніть Install (зелена кнопка +) поруч із ним.

3. Перейдіть до Extensions > Extensions і виберіть тип Payments. Знайдіть VibeFox Mollie Gateway, натисніть Install (зелена кнопка +), а потім Edit (кнопка з олівцем).

4. Введіть ліцензійний ключ і ключі API, як у кроках 3–5 для OpenCart 3. Сторінка налаштувань і її поля однакові в обох версіях. Відрізняється лише URL вебхука (див. Webhook URL).

Нове встановлення починається з вимкненим способом оплати та увімкненим тестовим режимом.

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

Усі налаштування розміщені на сторінці розширення: Extensions > Extensions > Payments > VibeFox Mollie Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка попереджає, якщо Mollie увімкнено, але ключ API поточного режиму порожній, а також якщо Mollie не підтримує валюту магазину за замовчуванням. В обох випадках спосіб оплати приховується під час оформлення замовлення. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

Під час збереження Title має містити від 1 до 128 символів, Sort Order має бути цілим числом, а Total має бути числом не менше 0; інакше нічого не зберігається. Ключ API, який не починається з test_ або live_, за якими йдуть щонайменше 30 літер і цифр, не зберігається: сторінка показує Settings saved, except the API key shown in red., помилка вказує на ключ, а раніше збережений ключ залишається.

Checkout

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

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

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

Sort Order: позиція Mollie серед способів оплати під час оформлення замовлення. Залиште поле порожнім або введіть ціле число.

Geo Zone: пропонувати Mollie лише для платіжних адрес у вибраній геозоні. За замовчуванням: All zones. Геозони налаштовуються в System > Localisation > Geo Zones.

Total: сума оформлення замовлення у валюті магазину за замовчуванням, яку має досягти замовлення, щоб Mollie було запропоновано. Залиште поле порожнім, щоб пропонувати Mollie за будь-якої суми.

Ключі API

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

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

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

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

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

Вебхук

Webhook URL: показується для довідки. Налаштовувати вебхук не потрібно: розширення надсилає цю адресу до Mollie з кожним платежем. В OpenCart 3 вона має вигляд https://your-store/index.php?route=extension/payment/wcp_mollie_gateway/webhook, в OpenCart 4 — https://your-store/index.php?route=extension/wcp_mollie_gateway/payment/wcp_mollie_gateway.webhook. Вона формується з адреси вітрини вашої інсталяції OpenCart. Вона має бути доступною з інтернету, інакше замовлення отримують статус лише тоді, коли покупець повертається з Mollie.

Замовлення

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення). Замовлення отримує статус лише після того, як Mollie повідомить про платіж. Кожне поле нижче перелічує ваші статуси замовлень OpenCart.

Order Status After Payment: статус, що встановлюється після успішної оплати. За замовчуванням: В обробці. Виберіть Complete, щоб позначати оплачені замовлення як завершені.

Awaiting Mollie Payment Status: покупець вибрав банківський переказ на сторінці Mollie; замовлення автоматично позначається як оплачене, коли Mollie отримує гроші. За замовчуванням: Очікується.

Mollie Payment On Hold Status: платіж потребує вашої перевірки (див. Order statuses). За замовчуванням: Очікується, оскільки в OpenCart немає статусу «На утриманні». Ви можете створити власний статус у System > Localisation > Order Statuses і вибрати його тут.

Payment Error Status: очікуваний банківський переказ або авторизований платіж не виконано, він прострочений або скасований. За замовчуванням: Невдало.

Refunded Status: платіж повністю повернено зі сторінки замовлення. За замовчуванням: Повернено.

Додатково

Logging: записує виклики API та вебхуки у файл molg_debug.log.php у папці журналів OpenCart (storage/logs). Відкрити файл через веб не можна. Помилки завжди записуються, навіть коли цей параметр вимкнено. Ключі API та дані покупців ніколи не записуються. За замовчуванням: вимкнено.

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

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

Імпорт / Експорт

Export: Download JSON зберігає налаштування у файл JSON. Ключі API не експортуються.

Import: вставте раніше експортований JSON і натисніть Import, щоб відновити налаштування. Збережені ключі API зберігаються.

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Mollie). На кроці Confirm Order покупець бачить ваш опис і примітку You will be redirected to Mollie to choose a payment method and pay. OpenCart створює замовлення на цьому кроці, все ще без статусу. Коли покупець натискає Confirm Order, розширення створює платіж Mollie на суму замовлення у валюті замовлення (JPY та ISK без десяткових знаків) з описом Order # і номером замовлення та надсилає покупця на розміщену сторінку оплати Mollie. Там покупець обирає один зі способів оплати, увімкнених у вашому обліковому записі Mollie, і сплачує. В OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення замовлення.

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

Коли покупець повертається, розширення так само перевіряє платіж через API Mollie. Потім замовлення отримує статус звичайним для OpenCart способом, із звичайними листами про замовлення та оновленням залишків, а покупець бачить сторінку успішного оформлення замовлення OpenCart з повідомленням 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. На OpenCart 4 ці повідомлення відображаються над сторінкою оформлення замовлення. Кошик зберігається. Якщо Mollie недоступний або ще не ухвалив рішення, з’являється сторінка Payment confirmation, яка просить покупця не платити знову та пропонує кнопку Check again; вебхук встановлює статус замовлення, щойно його отримано.

OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order, а OpenCart 4 зберігає одне замовлення для оформлення і оплачує те саме замовлення знову новим платежем Mollie. В будь-якому разі розширення розглядає всі замовлення одного кошика як один платіж. Коли покупець платить знову, ще відкритий платіж Mollie на ту саму суму використовується повторно, замість створення другого платежу до сплати. Якщо сума змінилася, старий відкритий платіж скасовується в Mollie, коли Mollie це дозволяє. Якщо тим часом старий платіж було сплачено, цей платіж підтверджується, і покупець переходить на сторінку успіху без нового платежу.

OpenCart 4 зберігає замовлення в оформленні до показу сторінки успіху. Якщо це замовлення було закрито без платежу (наприклад, банківський переказ прострочено або ви його скасували чи повернули), покупець повертається до оформлення замовлення з повідомленням Your previous order was cancelled or refunded. Please confirm the order again to pay with a new order., а наступне натискання Confirm Order оплачує нове замовлення. Оплачене, а потім скасоване або повернене замовлення того самого кошика більше не блокує кошик.

Якщо Mollie не може розпочати платіж, покупець залишається на кроці Confirm Order з коротким повідомленням над кнопкою, наприклад 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. Технічна причина записується в журнал.

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

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

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

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

Без статусу (відсутнє замовлення): покупця було перенаправлено до Mollie, і він не сплатив, або Mollie ще не підтвердив платіж. У Sales > Orders такі замовлення показуються лише з фільтром Order Status, встановленим на Missing Orders.

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

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

Mollie Payment On Hold Status (за замовчуванням Очікується): авторизований платіж очікує списання, Mollie повідомив про оскарження (chargeback), сплачена сума або валюта відрізнялися від замовлення, тестовий платіж було сплачено, поки магазин працює в робочому режимі (гроші не отримано), або платіж надійшов після того, як замовлення отримало інший статус (наприклад, його скасували). Примітка пояснює це. Перевірте платіж у Mollie Dashboard, а потім обробіть замовлення або поверніть платіж.

Payment Error Status (за замовчуванням Невдало): банківський переказ або авторизація замовлення не вдалися, прострочені або були скасовані.

Refunded Status (за замовчуванням Повернено): платіж повністю повернено через розширення.

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

Примітки — це записи в History замовлення, які покупець не бачить.

Вкладка VibeFox Mollie Gateway

У Sales > Orders відкрийте замовлення, оплачене через Mollie. Внизу сторінки замовлення, поруч із History та Additional, вкладка VibeFox Mollie Gateway показує ідентифікатор Mollie payment з позначкою Test mode для тестових платежів, Method, Status платежу, суми Paid / refunded, форму повернення коштів, історію повернень (дата, ідентифікатор повернення, сума, режим, статус Mollie, причина) та Mollie notes замовлення. Вкладка показується користувачам, які мають доступ до розширення.

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

На вкладці VibeFox Mollie Gateway введіть Amount (сума, яка ще не повернута, заповнюється автоматично), за бажання Reason (optional), і натисніть Refund via Mollie. Підтвердіть запитання Refund this amount through Mollie? This cannot be undone. Підтримуються повні та часткові повернення. Вам потрібне право змінювати розширення (встановлюється в System > Users > User Groups). Повернення виконуються в тій сумі та валюті, які списав Mollie, тому після розбіжності суми ви можете повернути не більше того, що покупець фактично сплатив, а не суму замовлення. Повернення надсилається за платежем, яким фактично оплачено замовлення, з ключем API того режиму, в якому його було здійснено, тож ключ цього режиму має бути вказаний. Якщо Mollie відхиляє повернення або повідомляє про нього як про невдале чи скасоване, вкладка показує повідомлення, і жодне повернення не реєструється. Успішне повернення додається до історії повернень і приміток разом з ідентифікатором повернення Mollie. Повне повернення встановлює замовленню Refunded Status без сповіщення покупця і без повернення товарів на склад, як під час ручної зміни статусу. Часткове повернення статус не змінює. Повернення доступні, щойно Mollie повідомив, що платіж оплачено.

Повернення товарів у Sales > Returns не повертають гроші через Mollie. Повернення, створені в Mollie Dashboard, не відображаються в замовленні; оскарження (chargeback) додає примітку.

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

Розширення працює з ліцензійним ключем VibeFox із vibefox.net. Блок ліцензії License — VibeFox Mollie Gateway є першим блоком на сторінці Extensions > Extensions > Payments > VibeFox Mollie Gateway > Edit, над налаштуваннями. Вставте ключ у License key і натисніть Activate. Після цього блок показує ключ замаскованим, статус (наприклад, дату, до якої ліцензія активна, та ваш домен), а також кнопки Check now, щоб повторно перевірити статус, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розташовано рядок Product: opencart-payment-mollie і посилання Manage licenses and domains in your account, що відкриває ваш обліковий запис на vibefox.net. Змінювати ключ можуть лише адміністратори з правом Modify на розширення. Тексти блоку відповідають мові адмінпанелі (включено англійську та російську).

Якщо ключ не приймається, блок пояснює причину, наприклад Key not found, This key belongs to another product, Domain limit reached або License expired on і дату. Після зміни адреси магазину або після звільнення місця для домену у вашому обліковому записі натисніть Check now. Якщо сервер ліцензій недоступний, розширення продовжує працювати з останнім відомим статусом.

Один ключ працює на одному домені: адреса магазину з налаштувань OpenCart. Видалення ключа з магазину не звільняє місце для домену. Звільніть місце у своєму обліковому записі на vibefox.net.

Без активного ключа Mollie не показується покупцям під час оформлення замовлення. Якщо платіж все ж розпочато, покупець бачить This payment method is not available. Please choose another one. Адміністратор, який увійшов в адмінпанель у тому самому браузері, усе ще бачить спосіб оплати в магазині з позначкою (unlicensed — visible to admins only), щоб ви могли налаштувати та перевірити розширення до купівлі ключа. В OpenCart 4 цей попередній перегляд недоступний: магазин не бачить входу адміністратора, тож без активного ключа спосіб оплати приховано для всіх. Після того як ви один раз відкриєте сторінку Edit, на Dashboard адмінпанелі з’явиться нагадування. Закрийте його кнопкою ×, щоб сховати на 7 днів. Наявні замовлення не зачіпаються: платежі, які вже розпочато, і далі підтверджуються, а повернення працюють.

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

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

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

Платіж пройшов, але замовлення залишається без статусу: вебхук не може достукатися до вашого магазину. URL, показаний у Webhook URL, має бути доступним з інтернету (без базової автентифікації та без файрвола, який заважає). Замовлення також отримає статус, коли покупець повернеться до магазину після оплати, або коли покупець натисне 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.

Покупець бачить помилку після Confirm Order: перегляньте поле Log на сторінці розширення. Там показано HTTP-код і повідомлення Mollie. 401 означає неправильний ключ API; 422 вказує на поле запиту, наприклад суму чи валюту, які Mollie не приймає. This payment method is not available. означає, що сесія оформлення замовлення більше не відповідає замовленню або спосіб оплати тим часом вимкнено: покупець має перезавантажити оформлення замовлення.

Замовлення має статус «На утриманні»: прочитайте примітки на вкладці VibeFox Mollie Gateway (див. Order statuses), а потім обробіть замовлення або поверніть платіж.

На вкладці немає форми повернення: вкладка пояснює причину: платіж ще не сплачено, його повністю повернено, ваша група користувачів не має права змінювати розширення, або платіж було здійснено в тестовому чи робочому режимі, а ключ API цього режиму не вказано (введіть його та відкрийте замовлення знову).

Для розробників: розширення запускає події OpenCart molg_supported_currencies (список валют) і molg_payment_data (запит на оплату та замовлення, до створення платежу Mollie).

Видалення

Перейдіть до Extensions > Extensions, виберіть тип Payments і натисніть Uninstall (червона кнопка −) поруч із VibeFox Mollie Gateway. Ліцензійний ключ і статус ліцензії цього розширення завжди видаляються. OpenCart завжди видаляє власні налаштування розширення: Enable/Disable, Sort Order, Geo Zone, Total і статуси замовлень із розділу Orders, які під час повторного встановлення повертаються до значень за замовчуванням. Подію OpenCart розширення також видаляється (на OpenCart 4 також його події та стартова дія, яка пропускає вебхук у режимі обслуговування). Якщо Delete Data on Uninstall увімкнено, видаляються інші налаштування шлюзу (назва, опис, тестовий режим, ключі API, журналювання) та журнал. Якщо вимкнено, вони зберігаються для подальшого повторного встановлення. Ідентифікатори платежів Mollie та записи про повернення завжди зберігаються, тож замовлення, оплачені раніше, можна повернути й після повторного встановлення. Наявні замовлення зберігають свої примітки про оплату.

На OpenCart 4, щоб також видалити файли розширення, після видалення перейдіть до Extensions > Installer, натисніть Uninstall (помаранчева кнопка −) поруч із VibeFox Mollie Gateway у списку встановлених розширень, а потім Delete (червона кнопка з кошиком), щоб видалити завантажений пакет.

Mollie є торговельною маркою її власника. Це розширення не пов’язане з Mollie і не схвалене Mollie.