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

Вимоги

WordPress: 5.8 або новіша.

WooCommerce: 6.0 або новіша, встановлений і активний. Плагін не активується без нього.

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

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

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

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

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

1. У WordPress перейдіть до Plugins > Add New > Upload Plugin, виберіть ZIP-файл плагіна та натисніть Install Now. Також можна завантажити папку wcp_niubiz_payment до /wp-content/plugins/ через FTP.

2. Натисніть Activate.

3. Відкрийте налаштування: WooCommerce > Settings > Payments > Niubiz > Manage або натисніть Settings під назвою плагіна на сторінці Plugins.

4. Введіть ліцензійний ключ VibeFox у блок ліцензії вгорі сторінки та натисніть Activate.

5. Залиште Sandbox mode увімкненим і введіть merchant ID, API user та API password тестового середовища (див. Налаштування).

6. Увімкніть Enable/Disable і зробіть кілька тестових платежів тестовими картками Niubiz.

7. Коли Niubiz сертифікує вашу інтеграцію, введіть робочі облікові дані та зніміть позначку з Sandbox mode.

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

Усі налаштування розміщені на одній сторінці: WooCommerce > Settings > Payments > Niubiz. Над полями сторінка попереджає, якщо валюта магазину не PEN і не USD, або якщо облікові дані поточного режиму заповнені не повністю (в обох випадках спосіб оплати приховується на оформленні замовлення), і показує Режим sandbox увімкнено: платежі йдуть у тестове середовище Niubiz, реальні списання не виконуються., поки режим sandbox увімкнений. У списку способів оплати 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 для тестового середовища, а після сертифікації — для робочого. Документація для розробників розміщена на desarrolladores.niubiz.com.pe.

Sandbox mode: Use the Niubiz sandbox (QA) environment — no real charges. Перемикає і адреси API, і набір облікових даних нижче. За замовчуванням: увімкнено. Зніміть позначку для реальних платежів.

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

Sandbox API user: API user тестового середовища.

Sandbox API password: API password тестового середовища.

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

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

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

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

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

Додатково

Debug log: Log API calls записує запити Niubiz у WooCommerce > Status > Logs, джерело wcp_niubiz_payment. Помилки записуються завжди. Облікові дані, токени, дані картки та покупця ніколи не записуються. За замовчуванням: вимкнено.

Delete data on uninstall: Remove the settings and logs of this plugin when it is deleted. Деактивація ніколи нічого не видаляє. Платіжні дані, збережені в замовленнях, зберігаються. За замовчуванням: вимкнено.

Налаштування версії 1.0, у якій був один набір облікових даних, переносяться автоматично: у поля sandbox, якщо тестовий режим був увімкнений, інакше — у поля робочого середовища.

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

Покупець вибирає спосіб оплати (за замовчуванням Credit or debit card (Niubiz)) і оформлює замовлення. Плагін запитує в Niubiz токен доступу та платіжну сесію на суму замовлення і надсилає покупця на сторінку оплати замовлення вашого магазину. У режимі sandbox оформлення замовлення та сторінка оплати показують РЕЖИМ SANDBOX: використовуйте тестові картки Niubiz. Реальні списання не виконуються.

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

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

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

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

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

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

Спосіб оплати працює в класичному оформленні замовлення, в блоці Checkout і на сторінці Pay for order. Він сумісний із WooCommerce High-Performance Order Storage (HPOS).

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

Замовлення

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

Очікує оплати: покупця надіслано на сторінку оплати, і він ще не оплатив.

В обробці: Niubiz схвалив платіж, і відповідь збіглася із замовленням. Замовлення лише з віртуальними товарами для завантаження переходять у статус «Виконано», як зазвичай у WooCommerce. У примітці до замовлення показано середовище, ID транзакції, код авторизації, номер покупки та марку картки з замаскованим номером. ID транзакції замовлення — це ID транзакції Niubiz.

Невдалий: картку відхилено. У примітці до замовлення показано причину Niubiz, код дії та номер покупки. Покупець може оплатити знову.

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

На утриманні, немає остаточної відповіді: Niubiz не відповів чітко, тож картку могли списати. Примітка містить номер покупки. Знайдіть його в консолі Niubiz: якщо транзакція схвалена і правильна, переведіть замовлення в статус «В обробці»; якщо ні — скасуйте його.

Скасовано: покупець натиснув Cancel order на сторінці оплати, або замовлення скасовано вами чи через тайм-аут резервування запасів WooCommerce.

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

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

Повернення та скасування з WooCommerce недоступні. Здійсніть повернення або скасування транзакції в консолі Niubiz і вручну оновіть замовлення, наприклад ручним поверненням у WooCommerce.

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

Плагін працює з ліцензійним ключем VibeFox, отриманим на vibefox.net. Блок ліцензії розміщено вгорі сторінки WooCommerce > Settings > Payments > Niubiz. Вставте ключ у License key і натисніть Activate. Блок показує статус, наприклад дату, до якої ліцензія активна, і ваш домен. Check now повторно перевіряє статус, Change key дозволяє ввести інший ключ, а Remove key видаляє його з цього сайту. Посилання Manage licenses and domains in your account відкриває ваш обліковий запис vibefox.net.

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

Без активного ключа Niubiz не показується покупцям на оформленні замовлення. Якщо платіж усе ж розпочато, покупець бачить Цей спосіб оплати недоступний. Виберіть інший. Авторизовані адміністратори магазину й далі бачать спосіб оплати, позначений як (unlicensed — visible to admins only), тож ви можете налаштувати та протестувати плагін до покупки ключа. Нагадування з'являється на сторінці Plugins і на сторінках WooCommerce. Наявні замовлення не змінюються: платежі, які вже розпочато в платіжній формі Niubiz, як і раніше авторизуються.

Коли ліцензія спливає, плагін продовжує працювати, але для оновлень і підтримки потрібне продовження. Статус автоматично перевіряється знову у фоновому режимі.

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

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

Платіж пройшов, але замовлення залишається в статусі Очікує оплати: у Niubiz немає вебхука для цієї платіжної форми, тому замовлення оновлюється лише відповіддю на авторизацію. Якщо замовлення «На утриманні» з приміткою, знайдіть номер покупки в консолі Niubiz. Якщо воно лишається «Очікує оплати», покупець не завершив форму; перевірте WooCommerce > Status > Logs, джерело wcp_niubiz_payment.

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

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

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

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

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

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

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

Блок ліцензії показує помилку: дотримуйтеся повідомлення в блоці. Наприклад, якщо ключ уже використовується на іншому домені, звільніть місце у своєму обліковому записі vibefox.net і натисніть Check now. Якщо адреса сайту змінилася, натисніть Check now, щоб активувати ключ для нового домену. Якщо сервер ліцензій недоступний, плагін продовжує працювати за останнім відомим статусом.

Для розробників: якщо Niubiz просить надсилати антифрод-поля, специфічні для мерчанта (MDD), додайте їх фільтром niubiz_p_merchant_define_data. Ключі — це MDD з номером, значення — до 100 символів. Інші фільтри: niubiz_p_cardholder_data (дані власника картки, що надсилаються з платіжною сесією), niubiz_p_purchase_number (номер покупки спроби, від 1 до 12 літер або цифр, унікальний для кожної спроби) та niubiz_p_icon (піктограма способу оплати).

Видалення

Деактивація плагіна зберігає всі дані. Щоб видалити його, деактивуйте та видаліть на сторінці Plugins. Ліцензійний ключ і статус ліцензії цього плагіна завжди видаляються. Налаштування шлюзу та журнали видаляються, лише якщо була увімкнена опція Delete data on uninstall. Дані Niubiz, збережені в замовленнях (ID транзакції, номер покупки, замасковану картку), є історією платежів і завжди зберігаються. Наявні замовлення зберігають свої примітки про оплату та ID транзакцій.

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