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 для тестовой среды (см. 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 для тестовой среды (QA) и, после сертификации, для рабочей среды. Платёж, который уже начат, всегда авторизуется с учётными данными своего режима.

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

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

Sandbox API user: пользователь API тестовой среды, обычно адрес электронной почты.

Sandbox API password: пароль API тестовой среды.

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 показывает номер покупки, среду (тестовую или рабочую), 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, поля рабочей среды в остальных случаях), и что покупатель платит в 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.