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

Вимоги

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

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

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

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

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

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

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

OpenCart 3

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

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

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

4. Залиште увімкненим Sandbox mode і введіть ідентифікатор мерчанта, користувача API та пароль API для sandbox (див. Configuration).

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

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

OpenCart 4

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

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

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

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

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

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

Усі параметри розміщено на сторінці розширення: Extensions > Extensions > Payments > VibeFox Niubiz Payment > Edit. Розділи перелічено ліворуч; кнопка Save під списком зберігає всю сторінку. Над параметрами сторінка попереджає, якщо в магазині не увімкнено жодної валюти PEN або USD, або якщо облікові дані поточного режиму заповнені не повністю (в обох випадках спосіб оплати приховується під час оформлення замовлення). Якщо типова валюта магазину не PEN і не USD, сторінка повідомляє, що Niubiz пропонується лише тоді, коли покупець платить у PEN або USD. Поки режим sandbox увімкнено, сторінка показує Sandbox mode is on: payments go to the Niubiz sandbox and no real charges are made. Без права на зміну розширення сторінка показує параметри, але не може їх зберегти.

Під час збереження неправильне значення не зберігається: над параметрами з'являється помилка, поле повертається до попереднього значення, а решта полів зберігається. Це стосується порожнього Title або такого, що довший за 128 символів, ідентифікатора мерчанта, який містить не лише цифри, URL логотипа, що не починається з https://, Sort Order, який не є цілим числом, і Total, який не є числом 0 або більшим.

Niubiz

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

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

Description: текст, який показується покупцеві на кроці Confirm Order над кнопкою підтвердження. За замовчуванням: Pay securely with Visa, Mastercard, American Express or Diners Club in the Niubiz payment form.

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

Geo Zone: пропонувати Niubiz лише для платіжних адрес у вибраній географічній зоні. За замовчуванням: All zones. Географічні зони налаштовуються в System > Localisation > Geo Zones. В OpenCart 4, якщо магазин не запитує платіжну адресу, використовується адреса доставки.

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

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

Niubiz надає вам ідентифікатор мерчанта, користувача API та пароль API для sandbox (QA) і, після сертифікації, для продуктивного середовища. Платіж, який уже розпочато, завжди авторизується з обліковими даними свого режиму.

Sandbox mode: використовує sandbox Niubiz без реальних списань. Він перемикає як кінцеві точки API, так і набір облікових даних, наведений нижче. За замовчуванням: on. Вимкніть його, щоб приймати реальні платежі з обліковими даними продуктивного середовища. Поки режим увімкнено, покупці бачать SANDBOX MODE: use Niubiz test cards — no real charges are made. на кроці Confirm Order та на сторінці оплати.

Sandbox merchant ID: код мерчанта (código de comercio) вашого облікового запису sandbox, лише цифри. Пробіли видаляються.

Sandbox API user: користувач API sandbox, зазвичай адреса електронної пошти.

Sandbox API password: пароль API sandbox.

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

Production API user: користувач API продуктивного середовища.

Production API password: пароль API продуктивного середовища.

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

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

Logo URL: необов'язкова адреса вашого логотипа, який показується в платіжній формі Niubiz. Має бути адресою https://. Залиште поле порожнім, щоб показувати назву магазину.

Замовлення

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

Order Status After Payment: Niubiz схвалив платіж, а номер покупки, сума та валюта збігаються із замовленням. За замовчуванням: Processing.

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

Додатково

Debug log: записує запити до API Niubiz та кроки оплати у файл niubiz_p_debug.log.php у папці журналів OpenCart (storage/logs). Файл не можна відкрити з веб-браузера, а коли він досягає 5 МБ, його переміщують до niubiz_p_debug.old.log.php. Помилки та попередження завжди записуються, навіть коли цей перемикач вимкнено. Паролі, токени, дані картки та покупця ніколи не записуються. За замовчуванням: off.

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

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

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

Export: Download JSON зберігає параметри у файл JSON. Паролі API не експортуються.

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

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

На кроці Payment Method покупець обирає спосіб оплати (за замовчуванням Credit or debit card (Niubiz)). На кроці Confirm Order покупець бачить ваш опис і примітку You will complete the payment in the secure Niubiz payment form. OpenCart створює замовлення на цьому кроці, все ще без статусу. В OpenCart 4 покупець обирає спосіб оплати кнопкою Choose у блоці способу оплати, у вікні Payment method options, і натискає Confirm Order внизу сторінки оформлення. Коли покупець натискає Confirm Order, розширення запитує в Niubiz токен доступу та платіжну сесію на суму замовлення у валюті замовлення і відкриває сторінку Niubiz payment вашого магазину. Якщо сесію створити не вдалося, покупець залишається на кроці Confirm Order з коротким повідомленням, наприклад We could not connect to Niubiz. Please try again in a few minutes.

На сторінці оплати платіжна форма Niubiz відкривається автоматично. Сторінка повідомляє: Complete the payment in the secure Niubiz payment form — your card details are entered on Niubiz, not on this site. Також є кнопка Pay із сумою замовлення для повторного відкриття форми та посилання Choose another payment method для повернення до оформлення замовлення. Потрібен JavaScript. Якщо форму Niubiz не вдалося завантажити, сторінка показує The Niubiz payment form could not be loaded. Please reload the page or try again later.

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

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

Немає відповіді від Niubiz: якщо Niubiz не дає остаточної відповіді (тайм-аут, помилка сервера, нечитабельна відповідь), замовлення отримує On Hold Status, а сторінка успіху показує We could not confirm your payment with Niubiz. Please do not pay again — the store will verify the payment and contact you. Якщо Niubiz схвалив платіж, який не відповідає замовленню, сторінка успіху показує Your payment was received and is being reviewed by the store. We will contact you if anything else is needed.

Запит відхилено: якщо Niubiz відхиляє сам запит (наприклад, через недійсні облікові дані або повторюваний номер покупки), замовлення залишається без статусу, додається примітка, і покупець бачить Niubiz could not process the payment and your card was not charged. Якщо API Niubiz у цей момент недоступний, покупець бачить We could not connect to Niubiz and your card was not charged. Please try again in a few minutes.

Замовлення змінено: якщо сума замовлення вже не відповідає сесії під час надсилання форми, платіж не авторизується, і покупець бачить Your order total has changed since the payment form was opened, so your card was not charged. Please check the total and pay again.

Сесія закінчилася: платіжна сесія Niubiz триває до 20 хвилин. Коли вона вже використана, залишилося менше 5 хвилин, вона належить іншому режиму чи ідентифікатору мерчанта або сума замовлення змінилася, сторінка оплати створює нову сесію.

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

OpenCart 4 тримає замовлення в оформленні, доки не буде показано сторінку успішного оформлення. Якщо це замовлення було закрито без оплати (наприклад, ви його скасували), покупця повертають до оформлення з повідомленням Your previous order was cancelled or its payment failed. Please confirm the order again., а наступне натискання Confirm Order оплачує нове замовлення. Якщо це замовлення вже має статус, а в кошику тепер інші товари або кількості, повідомлення таке: Your previous order has already been placed for other cart contents. Please confirm the order of your current cart again. В OpenCart 4 повідомлення, які повертають покупця до оформлення, наприклад The Niubiz payment could not be found. Please confirm your order again., показуються над сторінкою оформлення.

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

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

Замовлення

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

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

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

Order Status After Payment (типово Processing): Niubiz схвалив платіж, а відповідь збіглася із замовленням. Примітка показує середовище, ідентифікатор транзакції, код авторизації, номер покупки та бренд картки з замаскованим номером.

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

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

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

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

Вкладка VibeFox Niubiz Payment

У Sales > Orders відкрийте замовлення, оплачене через Niubiz. Унизу сторінки замовлення, поруч із History та Additional, вкладка VibeFox Niubiz Payment показує номер покупки, середовище (sandbox або продуктивне), Niubiz answer, ідентифікатор транзакції, код авторизації, картку, суму (і суму, схвалену Niubiz), виявлені проблеми, кількість спроб та Niubiz notes замовлення. Для замовлення в статусі очікування вкладка нагадує перевірити номер покупки в консолі Niubiz. Вкладка доступна лише для читання і показується користувачам, які мають доступ до розширення.

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

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

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

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

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

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

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

Niubiz не відображається під час оформлення замовлення: перевірте, що ліцензію активовано, увімкнено Enable/Disable, заповнено ідентифікатор мерчанта, користувача API та пароль API поточного режиму (поля sandbox у режимі sandbox, поля продуктивного середовища в інших випадках), і що покупець платить у PEN або USD. Сторінка параметрів показує попередження, якщо облікові дані або валюти вказано неправильно. Також перевірте, що платіжна адреса належить до вибраної Geo Zone, і що замовлення досягає Total, встановленого в налаштуваннях.

Платіж пройшов, але замовлення залишилося без статусу: Niubiz не має вебхука для цієї платіжної форми, тож замовлення отримує статус лише з відповіді на авторизацію. Якщо покупець не завершив форму, нічого не списано. Інакше перегляньте поле Log на сторінці розширення та знайдіть номер покупки в консолі Niubiz. Якщо Niubiz відповів, але статус встановити не вдалося, покупець бачить Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again., а розширення повторює спробу встановити статус, коли покупець відкриває сторінку оплати або знову підтверджує кошик.

Покупець бачить We could not connect to Niubiz: не вдалося отримати токен доступу. Перевірте користувача API та пароль API поточного режиму, а також чи може ваш сервер звернутися до API Niubiz. Увімкніть Debug log для отримання деталей.

Покупець бачить We could not start the Niubiz payment: Niubiz не створив платіжну сесію. Перевірте ідентифікатор мерчанта поточного режиму та журнал.

Покупець бачить This payment attempt was already processed: ту саму форму надіслано двічі. Покупець розпочинає оплату знову на сторінці оплати; картку не списують двічі.

Покупець бачить This order is already being paid: інший запит у цей момент авторизує той самий кошик. Покупець трохи почекає й перевірить електронну пошту, перш ніж повторити спробу.

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

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

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

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

Видалення

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

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

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