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

Вимоги

PrestaShop: 8.0–9.x.

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

Валюта: валюта кошика має бути EUR. Для інших валют спосіб оплати приховується під час оформлення замовлення.

Обліковий запис Nexi XPay: потрібен обліковий запис мерчанта Nexi XPay («Pagamento Semplice», інтеграція з переспрямуванням) з аліасом (ID терміналу) і MAC-ключем вашого терміналу. Тестові та робочі дані розділені: тестові беруться в тестовому розділі Nexi XPay або на порталі розробників (developer.nexi.it), робочі — у бек-офісі Nexi XPay після активації облікового запису мерчанта. У бек-офісі Nexi нічого налаштовувати не потрібно: адреса сповіщення передається з кожним платежем.

Публічний сайт: URL сповіщення має бути доступний з інтернету, без базової автентифікації та без правил брандмауера, що блокують Nexi. Режим обслуговування магазину його не блокує. Якщо сповіщення не може дійти до магазину, оплата все одно підтверджується підписаним поверненням покупця.

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

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

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

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

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

4. Залиште Test Mode увімкненим і введіть тестовий аліас та MAC-ключ (див. Налаштування).

5. Увімкніть Enable/Disable, натисніть Save і зробіть тестове замовлення. Коли все працює, введіть робочі аліас і MAC-ключ та вимкніть Test Mode.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Nexi XPay Gateway > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка показує Test mode is on: payments go to the Nexi XPay test environment, no real money is charged., поки ввімкнений тестовий режим. Вона попереджає, якщо шлюз увімкнено, але аліас або MAC-ключ поточного режиму порожні, або якщо основна валюта магазину не EUR. У таких випадках спосіб оплати приховується під час оформлення замовлення. Пробіли та переноси рядків навколо вставлених значень видаляються під час збереження.

Nexi XPay

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

Title: назва способу оплати, яку бачить покупець під час оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Credit Card (Nexi). У тестовому режимі оформлення замовлення та саме замовлення додають до назви (TEST MODE).

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

Тестове середовище

Тестові платежі йдуть на int-ecommerce.nexi.it і ніколи не списують кошти з реальних карток. Тестовий аліас і MAC-ключ беріть у тестовому розділі Nexi XPay або на порталі розробників (developer.nexi.it).

Test Mode: використовує тестове середовище Nexi XPay та тестові дані. Вимкніть його, щоб приймати реальні платежі з робочими даними. За замовчуванням: on.

Test Alias: аліас (ID терміналу) вашого тестового терміналу Nexi XPay.

Test MAC Key: ключ розрахунку MAC вашого тестового терміналу Nexi XPay.

Робоче середовище

Робочі аліас і MAC-ключ відображаються у вашому бек-офісі Nexi XPay (ecommerce.nexi.it) після активації облікового запису мерчанта.

Live Alias: аліас (ID терміналу) вашого робочого терміналу Nexi XPay.

Live MAC Key: ключ розрахунку MAC вашого робочого терміналу Nexi XPay.

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

Видалення збережених секретів: позначте Test MAC Key або Live MAC Key і натисніть Save, щоб видалити збережений ключ. Порожнє поле зберігає збережене значення.

Оплата

Notification URL: показано для довідки. Він передається Nexi з кожним платежем, тож у бек-офісі Nexi нічого налаштовувати не потрібно. З дружніми URL він виглядає так: https://your-shop/module/wcp_nexi_gateway/s2s?id_cart={id_cart}, можливо з кодом мови, наприклад /it/, а в кінці — номер кошика. Nexi надсилає результат платежу на цю адресу від сервера до сервера, а також передає його разом із поверненням покупця. Обидва варіанти підписуються однаково і перевіряються MAC-ключем середовища, в якому здійснено платіж, аліасом цього середовища та кодом транзакції, виданим для цього кошика. Результати, що не проходять перевірку, відхиляються і нічого не змінюють.

Capture: момент, коли списуються кошти.

Order Status After Payment: статус замовлення після успішної оплати.

Додатково

Debug Log: записує події платежів у logs/nexi_ip_debug.log.php у папці модуля. Відкрити файл через веб не можна. Ключі MAC, значення MAC, дані карток і адреси електронної пошти не записуються. Помилки та попередження, наприклад невдала перевірка MAC, записуються завжди, навіть коли опцію вимкнено. За замовчуванням: off.

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

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

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Credit Card (Nexi)) і підтверджує вибір. Наступна сторінка показує Redirecting to Nexi XPay for payment... і автоматично надсилає покупця на сторінку Nexi XPay, з кнопкою Pay Now на випадок, якщо перенаправлення не спрацювало. Платіж надсилається в EUR на суму кошика з новим кодом транзакції, електронною поштою покупця, описом Cart, номером кошика та назвою вашого магазину. Сторінка Nexi відкривається мовою кошика, якщо це італійська, англійська, іспанська, французька, німецька, японська, китайська, арабська, російська або португальська; інакше — англійською. На цьому етапі замовлення ще не існує.

Покупець сплачує і повертається до вашого магазину. Замовлення позначається оплаченим лише після перевіреного результату Nexi з точною сумою та валютою кошика: зі сповіщення від сервера до сервера або з підписаного повернення покупця, залежно від того, що надійде першим. Потім замовлення створюється, і покупець бачить стандартну сторінку підтвердження замовлення з повідомленням Your Nexi XPay payment has been received. Якщо Nexi повідомляє, що платіж очікує підтвердження, сторінка показує Your payment is pending confirmation from Nexi XPay. We will update your order as soon as the payment is confirmed. Для замовлення на утриманні (відкладене списання або ручна перевірка) вона показує We have received your Nexi XPay payment authorization. Your order will be processed shortly. Якщо платіж, що очікував, згодом не вдався, сторінка показує The payment was not completed. Please contact us.

Якщо результат ще не оброблено, коли покупець повертається, відкривається сторінка з повідомленням We have not received the payment confirmation from Nexi XPay yet. If you completed the payment, your order will be updated shortly. і кнопкою Check again. Сповіщення створює замовлення, щойно воно надходить.

Якщо платіж відхилено або покупець скасовує оплату на сторінці Nexi, він повертається до оформлення замовлення і бачить одне з повідомлень: The payment was not completed. Please try again or choose a different payment method., Payment was cancelled. Please try again. або We could not confirm the payment. If your card was charged, please contact us before paying again. Замовлення не створюється, кошик зберігається, і покупець може сплатити знову. Якщо для кошика вже є замовлення (наприклад, його оплатили в іншій вкладці), покупець переходить на підтвердження замовлення замість нової оплати.

Якщо модуль не налаштовано для поточного режиму, покупець бачить This payment method is not available right now. Please choose another payment method.

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

Модуль приймає платежі лише на сторінці Nexi XPay. Він не підтримує повернення з PrestaShop, збережені картки та OneClick, підписки або регулярні платежі, Pay-By-Link, вбудовані поля XPay Build і способи оплати, обрані в PrestaShop: сторінка Nexi показує способи, увімкнені на вашому терміналі.

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

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

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

Payment accepted, Delivered or Nexi XPay payment on hold: Nexi підтвердив платіж. Статус слідує за Order Status After Payment. Платіж записується з кодом транзакції Nexi як ID транзакції, а примітка показує код авторизації, код транзакції, марку картки та повідомлення Nexi.

Nexi XPay payment on hold (authorized): вибрано відкладене списання, платіж лише авторизовано. Спишіть його кнопкою Capture Nexi XPay payment на сторінці замовлення.

Awaiting Nexi XPay payment: Nexi повідомив, що платіж очікує підтвердження. Замовлення оновиться за остаточним результатом.

Nexi XPay payment on hold after payment: сума або валюта, отримані від Nexi, не збіглися з кошиком (замовлення не позначається як оплачене), або успішний платіж надійшов для вже скасованого замовлення. Примітка пояснює причину. Перевірте платіж у бек-офісі Nexi XPay та обробіть або поверніть замовлення.

Помилка оплати: платіж, що очікував, не пройшов. Той самий кошик не можна сплатити знову, тож покупцеві потрібно оформити нове замовлення.

Оплачене замовлення ніколи не понижується через пізнішу невдачу. Якщо для вже оплаченого замовлення надходить ще один успішний платіж, примітка просить повернути його в бек-офісі Nexi XPay, якщо це дублікат.

Блок оплати Nexi XPay

На сторінці замовлення показано блок Nexi XPay payment з кодом транзакції (codTrans), статусом і результатом Nexi, режимом списання, сумою, надісланою до Nexi, і отриманою сумою, кодом авторизації, маркою картки, повідомленням Nexi і датою, позначкою Test environment для тестових платежів і Nexi XPay notes замовлення.

Відкладене списання

Для авторизованого замовлення на утриманні натисніть у блоці Capture Nexi XPay payment (на кнопці вказано суму) і підтвердьте запитання Capture the authorized amount through Nexi XPay? Вам потрібне право редагувати замовлення. Модуль списує авторизовану суму в середовищі платежу, ключами цього середовища, фіксує платіж і встановлює статус відповідно до Order Status After Payment. Якщо списання не вдалося, блок показує помилку, до замовлення додається примітка, а замовлення залишається на утриманні. Повторне списання того самого платежу відхиляється.

Повернення

Повернення не здійснюються з PrestaShop, тому кнопки повернення для Nexi XPay немає. Зробіть повернення в бек-офісі Nexi XPay, а потім вручну зафіксуйте його в PrestaShop. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають кошти через Nexi.

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

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

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

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

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

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

Платіж пройшов, але замовлення не створено: ані сповіщення, ані повернення покупця не були прийняті. Перевірте, що магазин доступний з інтернету, що MAC-ключ і аліас відповідають середовищу (тестовому чи робочому) платежу, і увімкніть Debug Log, щоб побачити, що надіслав Nexi, у полі Log на сторінці модуля.

Сповіщення відповідає invalid_mac або invalid_alias: MAC-ключ або аліас у налаштуваннях не відповідають терміналу, який надіслав результат. Скопіюйте їх знову з тестового розділу або бек-офісу Nexi.

Сповіщення відповідає unknown_transaction: код транзакції не був виданий цим магазином для цього кошика. Результат ігнорується.

Сповіщення відповідає not_configured або busy: аліас або MAC-ключ середовища платежу порожні, або замовлення в цей момент оновлював інший запит, або замовлення не вдалося створити (наприклад, модуль вимкнено). Nexi повторить сповіщення.

URL сповіщення в браузері показує method_not_allowed: це нормально. URL приймає запити лише від Nexi.

Замовлення в статусі Nexi XPay payment on hold after payment: прочитайте Nexi XPay notes у блоці замовлення. Вибрано відкладене списання (списніть платіж кнопкою), сума або валюта не збіглися, платіж надійшов для скасованого замовлення, або Nexi XPay payment on hold вибрано як статус після оплати.

Capture Nexi XPay payment відсутній або не працює: кнопка показується лише для замовлень Nexi XPay, які перебувають на утриманні як авторизовані з відкладеним списанням, і лише для співробітників, яким дозволено редагувати замовлення. Якщо аліас або MAC-ключ середовища платежу порожні, блок про це повідомляє. Якщо списання не вдалося, прочитайте помилку в блоці та в примітках, наприклад Nexi XPay refused the capture з кодом і повідомленням Nexi.

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

Видалення

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

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