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

Вимоги

PrestaShop: від 8.0 до 9.x.

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

Валюта: перуанські соль (PEN) або долари США (USD). Спосіб оплати пропонується лише для кошиків в одній з цих валют. Для інших валют він приховується на етапі оформлення замовлення.

Обліковий запис Niubiz: Niubiz видає код мерчанта (código de comercio), API user і API password для кожного середовища. Облікові дані sandbox надає команда інтеграції Niubiz, а облікові дані робочого середовища — після того, як Niubiz сертифікує вашу інтеграцію. Налаштовувати вебхук не потрібно: Niubiz відповідає на авторизацію одразу.

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

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

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

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

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

4. Залиште увімкненим Sandbox mode і введіть merchant ID, API user та API password для sandbox (див. Налаштування).

5. Увімкніть Enable/Disable, натисніть Save і проведіть кілька тестових платежів тестовими картками Niubiz.

6. Після того як Niubiz сертифікує вашу інтеграцію, введіть облікові дані робочого середовища та вимкніть Sandbox mode.

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

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

Усі налаштування розташовані на сторінці модуля: Modules > Module Manager > VibeFox Niubiz Payment > Configure. Кожен розділ має власну кнопку Save, яка зберігає всю сторінку. Над полями сторінка попереджає, якщо в магазині не активна жодна валюта PEN або USD, або якщо облікові дані поточного режиму заповнені не повністю (в обох випадках спосіб оплати приховується на етапі оформлення замовлення). Якщо валюта магазину за замовчуванням не PEN і не USD, сторінка повідомляє, що Niubiz пропонується лише для кошиків у PEN або USD. Поки увімкнено режим sandbox, сторінка показує Режим sandbox увімкнено: платежі надсилаються до пісочниці Niubiz, реальні списання не здійснюються.

Niubiz

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

Title: назва способу оплати, яку бачать покупці на етапі оформлення замовлення. Вона також зберігається в замовленні як назва способу оплати. За замовчуванням: Credit or debit card (Niubiz). Обов'язкове поле: порожня назва не зберігається, залишається попередня.

Description: текст під способом оплати на етапі оформлення замовлення. За замовчуванням: Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.

Облікові дані Niubiz

Niubiz надає merchant ID, API user і API password для sandbox, а після сертифікації — для робочого середовища. Документація для розробників доступна на desarrolladores.niubiz.com.pe.

Sandbox mode: використовує тестове середовище Niubiz (QA) без реальних списань. Він перемикає і адреси API, і набір облікових даних нижче. За замовчуванням: увімкнено. Вимкніть для реальних платежів. Поки режим увімкнено, покупці бачать під способом оплати та на сторінці оплати РЕЖИМ SANDBOX: використовуйте тестові картки Niubiz — реальні списання не здійснюються.

Sandbox merchant ID: код мерчанта вашого тестового облікового запису, лише цифри. Пробіли видаляються. Якщо значення містить інші символи, сторінка показує помилку і зберігає попереднє значення. Інші поля зберігаються.

Sandbox API user: API user sandbox.

Sandbox API password: API password sandbox.

Production merchant ID: код мерчанта вашого робочого (афілійованого) облікового запису, лише цифри, з такою самою перевіркою.

Production API user: API user робочого середовища.

Production API password: API password робочого середовища.

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

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

Платіжна форма

Logo URL: необов'язкова HTTPS-адреса вашого логотипа, що відображається у платіжній формі Niubiz, приблизно 187 × 40 px. Без неї показується назва магазину. Адреса, яка не є коректною адресою https://, відхиляється з помилкою, і зберігається попереднє значення.

Додатково

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

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

Delete data on uninstall: якщо увімкнено, під час видалення модуля його налаштування та журнал видаляються. Платіжні дані, збережені для замовлень (спроби Niubiz, примітки до замовлень), і статус замовлення завжди зберігаються. За замовчуванням: вимкнено.

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

На етапі оплати покупець обирає спосіб оплати (за замовчуванням Credit or debit card (Niubiz)) і оформляє замовлення. Модуль запитує в Niubiz токен доступу та платіжну сесію на суму кошика у валюті кошика, і відкриває сторінку оплати вашого магазину Niubiz payment. На цьому етапі замовлення ще не існує.

На сторінці оплати платіжна форма Niubiz відкривається автоматично. На сторінці написано: Завершіть оплату в захищеній платіжній формі Niubiz — дані вашої картки вводяться на Niubiz, а не на цьому сайті. Там також є кнопка Pay із сумою кошика, щоб знову відкрити форму, і посилання Choose another payment method. Потрібен JavaScript. Якщо форму Niubiz не вдається завантажити, сторінка показує Не вдалося завантажити платіжну форму Niubiz. Оновіть сторінку або спробуйте пізніше.

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

Відхилена картка: замовлення не створюється. Покупець повертається на сторінку оплати з повідомленням Ваш платіж відхилено: та причиною від Niubiz і може повторити спробу тією самою або іншою карткою. Форма не відкривається знову поверх повідомлення; покупець натискає Pay.

Немає відповіді від Niubiz: якщо Niubiz не дає остаточної відповіді (тайм-аут, помилка сервера, нерозбірлива відповідь), замовлення створюється у статусі Niubiz payment on hold, а на сторінці підтвердження показується Не вдалося підтвердити ваш платіж у Niubiz. Будь ласка, не платіть повторно — магазин перевірить платіж і зв'яжеться з вами. Якщо Niubiz схвалив платіж, який не збігається з кошиком, сторінка показує Ваш платіж отримано і його перевіряє магазин. Ми зв'яжемося з вами, якщо знадобиться щось ще.

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

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

Сесія закінчилася: платіжна сесія Niubiz триває до 20 хвилин. Якщо вона вже використана, їй залишилося менше 5 хвилин, вона належить до іншого режиму чи іншого merchant ID, або сума кошика змінилася, сторінка оплати створює нову сесію.

Кожна спроба оплати отримує новий номер покупки: ID кошика та тризначний номер спроби (до 12 символів), оскільки Niubiz вимагає унікальний номер покупки для кожної авторизації.

Модуль приймає лише разові платежі картками. Він не має повернень і скасувань із PrestaShop, збережених карток, підписок і повторюваних платежів, вибору розстрочки (cuotas), а також платежів через PagoEfectivo, Yape та інші гаманці й QR-платежі. Замовлення, переведені в статус Niubiz payment on hold через втрачену відповідь, автоматично повторно не перевіряються.

Замовлення

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

No order yet: покупець перебуває на сторінці оплати і ще не заплатив, або картку відхилено чи запит відхилено. Існує лише кошик. Відмови та відхилення записуються в журнал модуля.

Payment accepted: Niubiz схвалив платіж, і відповідь збіглася з кошиком. Платіж записується з ID транзакції Niubiz, а примітка показує середовище, ID транзакції, код авторизації, номер покупки та марку картки з маскованим номером.

Niubiz payment on hold, approved but not matching: Niubiz схвалив платіж, у якого номер покупки, сума або валюта відрізняються від кошика, або відповідь не містить суми чи валюти. Замовлення не позначається оплаченим. Якщо схвалення в валюті кошика, схвалена сума записується як платіж з її ID транзакції. У примітці перелічено розбіжності. Перевірте транзакцію в консолі Niubiz.

Niubiz payment on hold, no definitive answer: Niubiz не дав чіткої відповіді, тому картку могли списати. Платіж не записується. Примітка містить номер покупки. Знайдіть його в консолі Niubiz: якщо транзакція схвалена і правильна, переведіть замовлення у статус Payment accepted; якщо ні — скасуйте його.

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

Блок оплати Niubiz

На сторінці замовлення показано блок Niubiz payment з номером покупки, середовищем (sandbox або робоче), ID транзакції, кодом авторизації, карткою та примітками замовлення. Для замовлення у статусі Niubiz payment on hold блок нагадує перевірити номер покупки в консолі Niubiz. Блок доступний лише для читання.

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

Повернення коштів і скасування недоступні з PrestaShop. Поверніть кошти або анулюйте транзакцію в консолі Niubiz і оновіть замовлення вручну. Стандартні кнопки повернення PrestaShop на сторінці замовлення не повертають гроші через Niubiz.

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

Модуль працює з ліцензійним ключем VibeFox з vibefox.net. Блок ліцензії License — VibeFox Niubiz Payment є першим блоком на сторінці Modules > Module Manager > VibeFox Niubiz Payment > Configure, над налаштуваннями. Введіть ключ у License key і натисніть Activate. Після цього блок показує маскований ключ, статус (наприклад, дату, до якої дійсна ліцензія, і ваш домен) та кнопки Check now, щоб перевірити статус знову, Change key, щоб ввести інший ключ, і Remove key, щоб видалити ключ із цього магазину. Нижче є рядок Product: presta-payment-niubiz і посилання Manage licenses and domains in your account, яке відкриває ваш обліковий запис vibefox.net. Змінювати ключ можуть лише співробітники з правом Configure для модуля. Тексти блоку відповідають мові адмін-панелі (включено англійську та російську).

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

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

Без активного ключа Niubiz не показується покупцям на етапі оформлення замовлення. Якщо все ж розпочато платіж, покупець бачить Цей спосіб оплати недоступний. Оберіть інший. Вітрина PrestaShop не знає, що ви ввійшли в адмін-панель, тому спосіб оплати приховується і для вас: модуль можна налаштувати до купівлі ключа, але перевірити його на етапі оформлення замовлення не можна. Нагадування з'являється в Modules > Module Manager на вкладці Alerts. Існуючі замовлення не зачіпаються: платежі, уже розпочаті, як і раніше підтверджуються.

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

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

Niubiz не з'являється на етапі оформлення замовлення: перевірте, що ліцензія активна, що Enable/Disable увімкнено, що merchant ID, API user і API password поточного режиму заповнені (поля sandbox у режимі sandbox, інакше поля робочого середовища), і що валюта кошика — PEN або USD. Сторінка налаштувань показує попередження, якщо облікові дані або валюти неправильні. У Payment > Preferences перевірте, що модуль дозволено для валюти кошика, країни покупця та групи покупця.

Платіж пройшов, але замовлення не створено: у Niubiz немає вебхука для цієї платіжної форми, тому замовлення створюється лише за відповіддю на авторизацію. Якщо покупець не завершив форму, замовлення немає. Інакше перегляньте поле Log на сторінці модуля і знайдіть номер покупки в консолі Niubiz. Якщо Niubiz відповів, але замовлення не вдалося створити (наприклад, модуль було вимкнено), покупець бачить Ваш платіж отримано, але замовлення не вдалося завершити автоматично. Зв'яжіться з нами — не платіть повторно., а модуль знову спробує створити замовлення, коли покупець відкриє сторінку оплати.

Покупець бачить «Не вдалося підключитися до Niubiz»: не вдалося отримати токен доступу. Перевірте API user і API password поточного режиму та те, що ваш сервер може звернутися до API Niubiz. Увімкніть Debug log, щоб побачити подробиці.

Покупець бачить «Не вдалося розпочати платіж Niubiz»: Niubiz не створив платіжну сесію. Перевірте merchant ID поточного режиму та журнал.

Покупець бачить «Цю спробу оплати вже оброблено»: ту саму форму надіслано двічі. Покупець розпочинає оплату знову на сторінці оплати; картку не списують двічі.

Покупець бачить «Це замовлення вже оплачується»: інший запит зараз авторизує той самий кошик. Покупець трохи почекає і перевірить електронну пошту, перш ніж повторити спробу.

Журнал показує, що Niubiz повідомив про повторну авторизацію: Niubiz вже знає цей номер покупки. Перевірте його в консолі Niubiz; покупець може повторити спробу з новим номером покупки.

Замовлення у статусі Niubiz payment on hold: прочитайте примітки в блоці Niubiz payment. Niubiz не дав остаточної відповіді або схвалив платіж, який не збігається з кошиком. Знайдіть номер покупки в консолі Niubiz і переведіть замовлення у статус Payment accepted або скасуйте його.

Помилка під час збереження налаштувань: merchant ID має містити лише цифри, а URL логотипа має бути коректною адресою https://. Попереднє значення зберігається.

Для розробників: якщо Niubiz просить надсилати специфічні для мерчанта антифрод-поля (MDD), їх може додати інший модуль через хук actionNiubizPMerchantDefineData. Дані власника картки, що надсилаються з платіжною сесією, можна змінити через хук actionNiubizPCardholderData.

Видалення

Перейдіть до Modules > Module Manager, відкрийте меню поруч із VibeFox Niubiz Payment і виберіть Uninstall. Ліцензійний ключ і статус ліцензії цього модуля завжди видаляються. Якщо Delete data on uninstall увімкнено, налаштування модуля та журнал видаляються. Якщо вимкнено, усі налаштування зберігаються для повторного встановлення. Спроби платежів Niubiz (номери покупок, середовище, ID транзакцій) і статус замовлення Niubiz payment on hold завжди зберігаються як історія платежів. Існуючі замовлення зберігають свої платіжні примітки та ID транзакцій.

Niubiz є торговельною маркою її власника. Цей модуль не афілійований з Niubiz і не схвалений Niubiz.