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

Вимоги

PrestaShop: 8.0–9.x.

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

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

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

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

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

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

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

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

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

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

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

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

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

Усі параметри розташовані на сторінці модуля: Modules > Module Manager > VibeFox Nets Nexi Gateway > Configure. Кожен розділ має власну кнопку 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., поки ввімкнено тестовий режим.

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

У заголовку розділу показано TEST або LIVE для обраного режиму.

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

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

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

Ключі API

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

Test Mode: тестовий режим використовує test.api.dibspayment.eu з тестовим секретним ключем; робочий режим — api.dibspayment.eu з робочим секретним ключем. Повернення та списання замовлення завжди використовують те середовище, в якому його було оплачено. За замовчуванням: увімкнено. Поки режим увімкнено, покупці бачать під способом оплати 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 saved secrets: позначте ключ і натисніть Save, щоб його видалити. Порожнє поле зберігає збережене значення.

Оплата

Webhooks: сповіщення Nets (вебхуки) реєструються автоматично з кожним платежем. У порталі Nets нічого налаштовувати не потрібно. Розділ показує адресу, на яку вони надсилаються. З ЧПУ-адресами вона має вигляд https://your-shop/module/wcp_nets_nexi_gateway/webhook, можливо з кодом мови, наприклад /en/. Якщо адреса не є публічною HTTPS-адресою, розділ попереджає, що магазин не отримує вебхуки; тоді платежі підтверджуються, коли покупець повертається до магазину, або через Nets: check payment status and capture: на сторінці замовлення. Реєструються такі події:

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

Order Status After Payment: статус замовлення після того, як Nets підтвердив і списав платіж.

Додатково

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

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Nets Easy) і підтверджує. Модуль створює платіж Nets на суму кошика у валюті кошика, передаючи товари, доставку, подарункове пакування та знижки як позиції замовлення, і надсилає покупця на розміщену сторінку оплати Nets. Номер платежу в Nets — це номер кошика. Електронна пошта, ім'я, адреса й телефон покупця передаються в Nets, якщо Nets приймає їхній формат. На сторінці Nets посилання на сторінку умов і положень вашого оформлення (якщо не задано — головна сторінка магазину). На цьому етапі замовлення ще не існує.

Після оплати покупець повертається до вашого магазину. Замовлення позначається оплаченим лише після підтвердження Nets: модуль отримує платіж з API Nets, порівнює зарезервовану суму й валюту з кошиком, списує резервування і тільки після цього створює замовлення. Це відбувається під час вебхука або при поверненні покупця — залежно від того, що станеться раніше. Потім покупець бачить стандартну сторінку підтвердження замовлення. Якщо платіж поки що не вдалося підтвердити (Nets був недоступний або інший запит у цей момент його підтверджував), сторінка Payment confirmation показує Your Nets payment is being confirmed. Your order will be created 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. Кошик зберігається. За нової спроби модуль спочатку перевіряє попередній платіж: якщо він уже оплачений, створюється замовлення замість нового платежу. Інакше попередня сесія Nets закривається до початку нової.

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

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

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

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

No order yet: покупця надіслано до Nets, і він не оплатив, або платіж ще не підтверджено. Існує лише кошик.

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

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

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

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

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

Блок оплати Nets Easy

На сторінці замовлення показано блок Nets Easy payment з ідентифікатором платежу, ідентифікатором списання, середовищем (з позначкою Test environment для тестових платежів), статусом, сумами, зарезервованими та списаними в Nets, сумою замовлення та поверненою сумою, історією повернень і Nets notes замовлення. Кнопки блока працюють для всіх співробітників, які можуть редагувати замовлення; доступ до сторінок модулів не потрібен.

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

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

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

Модуль не створює кредитових нот. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають кошти через Nets. Повернення, зроблені в порталі Nets, не синхронізуються; за потреби оновіть замовлення вручну.

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

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

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

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

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

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

Оплату виконано, але замовлення не створено: вебхук не дійшов до вашого магазину. Перевірте, що магазин використовує HTTPS і ЧПУ-адреси, щоб адреса в Webhooks була публічною HTTPS-адресою без «&», і що секретний ключ середовища платежу задано. Замовлення також створюється, коли покупець повертається до магазину після оплати.

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

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

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

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

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

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

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

Видалення

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

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