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

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 для песочницы и, после сертификации, для боевого режима. Документация для разработчиков доступна на desarrolladores.niubiz.com.pe.

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

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 боевого режима.

Сохранённые пароли больше не показываются. Поле остаётся пустым и показывает Сохранён — оставьте пустым, чтобы не менять. Вводите новое значение, только если хотите его изменить.

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 и не одобрен им.