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 сертифицирует вашу интеграцию. Настраивать webhook не нужно: 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.

Способ оплаты работает в классическом оформлении заказа, в блоке «Оформление заказа» и на странице 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 нет webhook, поэтому заказ обновляется только ответом на авторизацию. Если заказ «На удержании» с примечанием, найдите номер покупки в консоли 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.