VibeFox Nets Nexi for OpenCart — Допомога

Вимоги

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

PHP: 8.0 або новіша.

Обліковий запис Nets: потрібні секретні ключі вашого облікового запису Nets Easy (тестовий і робочий). Використовуються лише секретні ключі. Ключі checkout не потрібні, оскільки покупці платять на розміщеній сторінці оплати Nets.

Валюти та способи оплати: розширення саме по собі не обмежує валюти. Використовуйте валюти, увімкнені у вашому обліковому записі Nets; непідтримувану валюту Nets повідомить під час створення платежу. Які способи оплати побачить покупець, залежить від вашого договору з Nets, країни та валюти.

HTTPS для вебхуків: Nets звертається лише до публічних HTTPS-адрес довжиною не більше 256 символів і без «&», тому вашому магазину потрібен HTTPS для отримання вебхуків. Без HTTPS платіж усе одно підтверджується, коли покупець повертається до магазину, або під час перевірки статусу на сторінці замовлення.

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

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

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

OpenCart 3

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

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

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

4. Скопіюйте тестовий секретний ключ із тестового порталу Nets Easy і вставте його в поле Test Secret Key (див. Налаштування). На порталі Nets нічого налаштовувати не потрібно.

5. Увімкніть Enable/Disable, залиште Test Mode увімкненим, натисніть Save і зробіть тестове замовлення. Потім введіть робочий секретний ключ і вимкніть Test Mode.

OpenCart 4

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

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

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

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

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

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

Усі налаштування містяться на сторінці розширення: Extensions > Extensions > Payments > VibeFox Nets Nexi Gateway > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над налаштуваннями сторінка попереджає, якщо відсутній секретний ключ обраного режиму, наприклад Nets Nexi: enter the Test Secret Key — the payment method is hidden at checkout until the key of the selected mode is set., і показує Nets Nexi is in test mode: payments go to the Nets test environment and no real money is charged., поки ввімкнено тестовий режим. Без права змінювати розширення сторінка показує налаштування, але не може їх зберегти.

Під час збереження поле Title не може бути порожнім (до 128 символів), Sort Order має бути цілим числом, Total — числом 0 або більше, а гео-зона та статуси замовлень мають існувати; якщо будь-яке поле заповнено неправильно, нічого не зберігається.

Nets Nexi (країни Північної Європи)

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

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

Description: текст, який покупець бачить на кроці Confirm Order. За замовчуванням: Pay securely with Nets Easy.

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

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

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

Ключі API

Скопіюйте секретні ключі з порталу Nets Easy у розділі Company > Integration: тестовий портал (test.portal.dibspayment.eu) для тестового ключа та робочий портал (portal.dibspayment.eu) для робочого ключа. У розділі є посилання на обидва портали. Ключі checkout не потрібні.

Test Mode: тестовий режим використовує test.api.dibspayment.eu з тестовим секретним ключем; робочий режим використовує api.dibspayment.eu з робочим секретним ключем. Повернення коштів і списання за замовленням завжди виконуються в тому середовищі, де було сплачено замовлення. За замовчуванням: увімкнено. Поки режим увімкнено, покупці на кроці Confirm Order бачать Test mode: no real money will be charged.

Test Secret Key: ваш секретний ключ API тестового середовища Nets.

Live Secret Key: ваш секретний ключ API робочого середовища Nets.

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

Оплата

Webhooks: сповіщення Nets (вебхуки) реєструються автоматично з кожним платежем. На порталі Nets нічого налаштовувати не потрібно. Поле показує адресу, на яку вони надсилаються. Для OpenCart 3 вона має вигляд https://your-store/index.php?route=extension/payment/wcp_nets_nexi_gateway/webhook, для OpenCart 4 — https://your-store/index.php?route=extension/wcp_nets_nexi_gateway/payment/wcp_nets_nexi_gateway.webhook. Вона формується з адреси вітрини вашої інсталяції OpenCart. Якщо це не публічна HTTPS-адреса, поле попереджає, що магазин не отримує вебхуки; тоді платежі підтверджуються, коли покупець повертається до магазину, або через Nets: check payment status and capture на сторінці замовлення. Реєструються такі події:

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

OpenCart створює замовлення на кроці Confirm Order без статусу (відсутнє замовлення, missing order). Статус воно отримує лише після того, як платіж зчитано з API Nets (вебхук, повернення покупця або Nets: check payment status and capture на сторінці замовлення) і відповідне резервування списано. Кожне поле статусу нижче перелічує ваші статуси замовлень OpenCart.

Order Status After Payment: статус замовлення після того, як Nets підтвердив і списав платіж. За замовчуванням: Processing. Виберіть Complete, щоб позначати оплачені замовлення як виконані.

Nets Payment On Hold Status: сума або валюта відрізняються від замовлення, списання не вдалося або покупець заплатив після скасування замовлення. Нічого не списується автоматично, а примітка пояснює причину. За замовчуванням: Pending, оскільки в OpenCart немає статусу On hold. Ви можете створити власний статус у System > Localisation > Order Statuses і вибрати його тут.

Cancelled Status: встановлюється, коли резервування замовлення скасовано на порталі Nets. За замовчуванням: Canceled.

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

Додатково

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

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

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

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

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

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

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Nets Easy). На кроці Confirm Order покупець бачить ваш опис і примітку You will be redirected to the Nets payment page to pay securely. OpenCart створює замовлення на цьому кроці, ще без статусу. Коли покупець натискає Confirm Order, розширення створює платіж Nets на суму замовлення у валюті замовлення, передає товари, доставку та інші підсумки замовлення (купони, ваучери, збори) як рядки замовлення і надсилає покупця на розміщену сторінку оплати Nets. На OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення. Посиланням на платіж у Nets є номер замовлення OpenCart. Електронна адреса, ім'я, адреса доставки та телефон покупця передаються в Nets, якщо Nets приймає їхній формат. На сторінці Nets розміщено посилання на сторінку умов оформлення замовлення вашого магазину (якщо її не задано — на головну сторінку магазину).

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Nets: розширення зчитує платіж з API Nets, порівнює зарезервовані суму та валюту із замовленням, списує резервування і лише потім встановлює статус замовлення. Це відбувається через вебхук або коли покупець повертається — залежно від того, що станеться раніше. Після цього замовлення отримує статус стандартним для OpenCart способом, зі звичайним листом про замовлення та оновленням залишків, а покупець бачить сторінку успішного оформлення замовлення OpenCart. Якщо платіж ще не вдалося підтвердити (Nets був недоступний або інший запит саме його підтверджував), сторінка Payment confirmation показує Your Nets payment is being confirmed. Your order will be updated as soon as it is confirmed — please do not pay again. з кнопками Check again і Back to checkout.

Якщо покупець скасовує платіж на сторінці Nets, він повертається до оформлення з повідомленням The Nets payment was cancelled. You can try again or choose another payment method. Якщо нічого не було оплачено, виводиться The payment was not completed. You can try again or choose another payment method. На OpenCart 4 ці повідомлення показуються над сторінкою оформлення. Кошик зберігається. OpenCart 3 створює нове замовлення щоразу, коли показується крок Confirm Order, а OpenCart 4 зберігає одне замовлення для оформлення і оплачує те саме замовлення знову новим платежем Nets. Під час нової спроби розширення спершу перевіряє попередні платежі кошика; якщо один із них уже оплачено, підтверджується саме це замовлення, а не створюється новий платіж. Інакше попередні сесії Nets закриваються перед початком нової. Коли інше замовлення з того самого кошика вже оплачене або утримується, покупець переходить на сторінку успішного оформлення.

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

Якщо Nets не може розпочати платіж, покупець залишається на кроці Confirm Order з коротким повідомленням, наприклад Nets could not start the payment with the details of this order. Please check your address and phone number, or choose another payment method., This payment method is temporarily unavailable. Please choose another payment method. або The payment service could not be reached. Please try again in a moment. Сума замовлення, що дорівнює нулю, дає The order total must be greater than zero to pay with Nets. Деталі записуються в журнал.

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

Розширення використовує лише розміщену сторінку оплати. Воно не має вбудованого на сторінці оформлення Nets, підписок або періодичних платежів, збережених карток, рахунків-фактур зі зборами, режиму лише авторизації та часткових списань за відправленнями.

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

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

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

Order Status After Payment (default Processing): Nets підтвердив і списав платіж. Примітка показує ID платежу, ID списання та спосіб оплати.

Nets Payment On Hold Status (default Pending): сума або валюта в Nets відрізняються від замовлення (не списано), списання було відхилено або покупець заплатив після того, як замовлення було скасовано (зарезервовано, не списано). Примітка пояснює це. Нічого не списується автоматично. Після перевірки замовлення здійсніть списання через Nets: check payment status and capture або скасуйте резервування на порталі Nets.

Cancelled Status (default Canceled): резервування замовлення було скасовано, наприклад на порталі Nets.

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

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

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

Вкладка VibeFox Nets Nexi Gateway

В Sales > Orders відкрийте замовлення, оплачене через Nets. Унизу сторінки замовлення, поруч із History і Additional, вкладка VibeFox Nets Nexi Gateway показує блок Nets Easy payment: ID платежу, ID списання, середовище (з міткою Test environment для тестових платежів), статус і спосіб оплати, суми, зарезервовані та списані в Nets, суму замовлення і повернуту суму, форму повернення коштів, історію повернень і Nets notes замовлення. Вкладка показується користувачам, які мають доступ до розширення; її кнопки потребують права змінювати розширення (задається в System > Users > User Groups).

Nets: check payment status and capture: показується для замовлень, які ще не оплачені. Вона зчитує платіж з Nets і списує резервування, що відповідає замовленню, зокрема після невдалого списання або після перевірки замовлення на утриманні. Якщо нічого не змінилося, примітка пояснює причину, наприклад, що покупець ще не завершив оплату. Статус, встановлений цією кнопкою, як і статус, встановлений поверненням коштів, змінюється напряму, як ручна зміна статусу, без листів і руху товарів на складі.

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

На вкладці введіть Amount (підставляється сума, яку ще не повернено), за потреби Reason (optional), і натисніть Refund via Nets. Підтвердіть запитання Refund this amount through Nets? This cannot be undone. Повні та часткові повернення можливі після списання платежу, до суми замовлення; платіж, який лише зарезервовано, можна скасувати на порталі Nets. Повернення йде на списання замовлення в тому середовищі, де платіж було сплачено, тож секретний ключ цього середовища має бути заданий. Якщо Nets не приймає повернення, вкладка показує помилку і повернення не записується. Успішне повернення додається до історії повернень і приміток із ID повернення Nets. Повне повернення встановлює замовленню Refunded Status; часткове повернення статус не змінює.

Повернення товарів у Sales > Returns не повертають гроші через Nets. Повернення, зроблені на порталі Nets, не синхронізуються; за потреби оновіть замовлення вручну.

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

Розширення працює з ліцензійним ключем VibeFox, отриманим на vibefox.net. Блок ліцензії License — VibeFox Nets Nexi Gateway — перший блок на сторінці Extensions > Extensions > Payments > VibeFox Nets Nexi Gateway > Edit, над налаштуваннями. Вставте ключ у поле License key і натисніть Activate. Після цього блок показує ключ у прихованому вигляді, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен), а також кнопки Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче розміщено рядок Product: opencart-payment-nets-nexi і посилання 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. Якщо сервер ліцензій недоступний, розширення продовжує працювати за останнім відомим статусом.

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

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

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

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

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

Платіж пройшов, але замовлення залишається без статусу: вебхук не дійшов до вашого магазину. Перевірте, що магазин працює через HTTPS, щоб адреса в Webhooks була публічною HTTPS-адресою, і що секретний ключ середовища платежу заданий. Замовлення також отримує статус, коли покупець повертається до магазину після оплати, або після натискання Nets: check payment status and capture на вкладці замовлення.

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

Вебхук відповідає Unknown payment: платіж створено не цим магазином.

Вебхук відповідає Busy, retry later, Payment lookup failed або Payment not reserved yet: інший запит підтверджував той самий кошик, API Nets був недоступний або резервування ще не було видно. Nets повторить вебхук автоматично.

Вебхук відповідає Order could not be updated, retry later: не вдалося встановити статус замовлення. Nets повторить вебхук. Увімкніть Debug log, щоб побачити причину.

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

Покупець бачить помилку після Confirm Order: увімкніть Debug log і перегляньте поле Log на сторінці розширення. This payment method is temporarily unavailable. Please choose another payment method. зазвичай означає неправильний або відсутній секретний ключ. Відхилену валюту Nets повідомляє в журналі. This payment method is not available. означає, що сесія оформлення більше не відповідає замовленню, або спосіб оплати тим часом вимкнено: покупець перезавантажує сторінку оформлення.

Покупець бачить We could not match this payment to an order: посилання для повернення неповне або належить іншому замовленню. Якщо з покупця списали кошти, знайдіть платіж на порталі Nets і перевірте замовлення.

Замовлення після оплати перебуває в статусі утримання: прочитайте Nets notes на вкладці. Якщо списання відхилено, повторіть його через Nets: check payment status and capture або спишіть платіж на порталі Nets. Якщо сума або валюта не збігаються, перевірте платіж на порталі Nets. Якщо покупець заплатив після скасування, перевірте замовлення та спишіть або скасуйте резервування.

Refund via Nets відсутнє або не працює: повернення можливі лише після списання платежу; тоді вкладка показує ID списання. Повернення використовує секретний ключ того середовища, в якому було оплачено замовлення, тож цей ключ має бути заданий; інакше вкладка повідомить, якого ключа середовища бракує.

Для розробників: перед створенням платежу розширення викликає подію OpenCart nng_create_payment_payload із тілом запиту та замовленням; nng_currency_decimals змінює кількість десяткових знаків валюти.

Видалення

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

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

Nets, Nets Easy та Nexi є торговельними марками їхніх відповідних власників. Це розширення не пов'язане з Nets або Nexi і не схвалене ними.