VibeFox ePay.bg for PrestaShop — Помощь

Требования

PrestaShop: от 8.0 до 9.x.

PHP: 8.0 или новее. Модуль не устанавливается на более старых версиях PHP.

Валюта: болгарский лев (BGN), евро (EUR) или доллар США (USD). Корзина списывается в своей валюте с 2 знаками после запятой. Для корзин в других валютах способ оплаты скрыт на этапе оформления заказа.

Аккаунт ePay.bg: нужны номер клиента (MIN) и секретный ключ из вашего мерчант-профиля ePay.bg: рабочие — на www.epay.bg, тестовые — на demo.epay.bg (тестовый аккаунт регистрируется отдельно). Также нужно указать URL уведомлений вашего магазина в мерчант-профиле.

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

Установка

1. В панели администратора перейдите в Modules > Module Manager и нажмите Upload a module. Выберите ZIP-файл модуля.

2. По завершении загрузки нажмите Configure или позже найдите VibeFox ePay.bg Gateway в списке модулей и нажмите Configure.

3. Введите лицензионный ключ VibeFox в поле License key блока лицензии вверху страницы Configure и нажмите Activate (см. раздел Лицензионный ключ).

4. Введите MIN и секретный ключ для тестового и/или рабочего режима (см. раздел «Настройка»).

5. Скопируйте URL из раздела Payment notifications (IPN) в поле URL for receiving notifications мерчант-профиля ePay.bg — и в демо-, и в рабочем профиле. Без него заказ не создаётся.

6. Включите Enable/Disable и нажмите Save. Оформите тестовый заказ в тестовом режиме, затем выключите Test Mode.

При установке модуль создаёт статус заказа ePay.bg payment on hold. PrestaShop предлагает новый способ оплаты для всех валют, стран и групп клиентов. Ограничить их можно в Payment > Preferences.

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox ePay.bg Gateway > Configure. Каждая кнопка Save сохраняет всю страницу. Над полями страница показывает ошибку, если основная валюта магазина не BGN, EUR или USD; предупреждение, если шлюз включён, но MIN или секретный ключ выбранного режима пусты (тогда он скрыт на этапе оформления заказа, а при сохранении появляется то же предупреждение); и Test mode is on: payments go to demo.epay.bg and no real money is charged. — пока включён тестовый режим.

ePay.bg

Enable/Disable: Enable ePay.bg Payment Gateway включает или выключает способ оплаты. По умолчанию: выключено.

Title: название способа оплаты, которое видят покупатели на этапе оформления заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: ePay.bg. Обязательное поле.

Description: текст под способом оплаты на этапе оформления заказа. По умолчанию: Pay securely via ePay.bg with a bank card or your ePay.bg account.

Аккаунт ePay.bg

Номер клиента (MIN) и секретный ключ указаны в вашем мерчант-профиле на www.epay.bg (рабочий) и demo.epay.bg (тестовый аккаунт, регистрируется отдельно).

Test Mode: включает тестовый режим. Покупатели перенаправляются в демо-среду ePay.bg, а запросы подписываются тестовыми учётными данными. По умолчанию: включено.

Test Merchant ID (MIN): номер клиента (MIN) вашего мерчант-аккаунта demo.epay.bg.

Test Secret Key: секретный ключ вашего мерчант-аккаунта demo.epay.bg (64 символа).

Live Merchant ID (MIN): номер клиента (MIN) вашего мерчант-аккаунта www.epay.bg.

Live Secret Key: секретный ключ вашего мерчант-аккаунта www.epay.bg (64 символа), используется для подписи HMAC-SHA1.

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

Clear saved secret keys: отметьте ключ и нажмите Save, чтобы удалить его. Пустое поле сохраняет сохранённое значение.

Payment notifications (IPN)

Уведомление сообщает вашему магазину, что платёжный запрос оплачен, отклонён или истёк. В поле Notification URL показан URL, который нужно указать как URL for receiving notifications в мерчант-профиле ePay.bg, рабочем и тестовом. При включённых ЧПУ он выглядит так: https://your-shop/module/wcp_epaybg_gateway/notify, возможно с кодом языка, например /en/. Скопируйте URL точно так, как он показан в настройках. Заказы создаются только этими подписанными уведомлениями; возврат покупателя в магазин не создаёт и не оплачивает заказ.

ePay.bg сообщает такие результаты по каждому счёту:

Уведомления без действительной контрольной суммы отклоняются, и ePay.bg продолжает их отправлять. Контрольная сумма проверяется секретным ключом каждого режима, у которого он есть, поэтому платежи, начатые до переключения между тестовым и рабочим режимом, всё равно подтверждаются. Платёж должен поступить в том режиме, в котором был сделан запрос; иначе заказ переходит в статус ePay.bg payment on hold. Без URL уведомлений в мерчант-профиле заказ не создаётся.

Payment request

Invoice Prefix: только цифры (до 10), ставятся перед ID корзины и образуют номер счёта ePay.bg, например 00001 + 123 = 00001123. Используйте разные префиксы для разных магазинов на одном аккаунте ePay.bg. Другие символы удаляются при сохранении с предупреждением. Изменить префикс позже безопасно: открытые платёжные запросы находятся по счёту, сохранённому для каждого из них. По умолчанию: 00001.

Expiration Time: время, по истечении которого неоплаченный платёжный запрос истекает; ePay.bg сообщает о нём как об истёкшем, и заказ не создаётся. Выберите 1, 3, 6, 12, 24, 48 или 72 часа. Время передаётся по болгарскому времени, независимо от часового пояса вашего магазина. По умолчанию: 24 часа.

Language: язык платёжной страницы ePay.bg, английский или болгарский. По умолчанию: английский.

Order Status After Payment: статус заказа, который присваивается после успешной оплаты.

Advanced

Logging: записывает платёжные запросы и уведомления в logs/epay_bp_debug.log.php в папке модуля. Файл нельзя открыть из веба. Секретные ключи и данные карт не записываются. По умолчанию: выключено. Ошибки записываются всегда, в том числе когда журнал выключен.

Log: показывает размер и последние записи журнала. Нажмите Clear log, чтобы очистить его.

Delete Data on Uninstall: если включено, при удалении модуля удаляются настройки шлюза и журнал. Записи платежей ePay.bg, статус заказа ePay.bg payment on hold и заказы всегда сохраняются. По умолчанию: выключено.

Оформление заказа

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию ePay.bg) и подтверждает выбор. Покупатель видит Redirecting to ePay.bg for payment... и перенаправляется на ePay.bg с подписанным платёжным запросом на сумму корзины в валюте корзины, с номером счёта и сроком действия. На ePay.bg платёж отображается как Cart с номером корзины. На странице также есть кнопка Pay via ePay.bg на случай, если перенаправление не запустилось, и кнопка Cancel. На ePay.bg покупатель платит банковской картой или с помощью учётной записи ePay.bg. На этом этапе заказа ещё не существует.

После оплаты покупатель возвращается в ваш магазин. Заказ создаётся только при получении подписанного уведомления ePay.bg. Если оно уже пришло, покупатель видит стандартную страницу подтверждения заказа. Если нет, страница Payment confirmation показывает Thank you. Your payment is being confirmed by ePay.bg — your order will be created as soon as ePay.bg confirms it, and you will receive an e-mail. с кнопками Check again и Back to checkout.

Если покупатель отменяет оплату на ePay.bg, он возвращается к оформлению заказа с сообщением The ePay.bg payment was cancelled. You can try again or choose another payment method. Если ePay.bg сообщил, что запрос отклонён или истёк, сообщение будет The payment was not completed. You can try again or choose another payment method. Корзина сохраняется. Новая попытка для той же корзины использует тот же номер счёта.

Если корзину нельзя оплатить через ePay.bg, покупатель остаётся на оформлении заказа с коротким сообщением, например ePay.bg payments are temporarily unavailable. Please choose another payment method. или о том, что ePay.bg не принимает платежи в валюте корзины.

Уведомление работает, пока магазин находится в режиме обслуживания, и не блокируется ограничением по стране вашего магазина.

Модуль принимает только разовые платежи через ePay.bg. Нет возвратов из PrestaShop, сохранённых карт, подписок или регулярных платежей, а также кодов оплаты наличными EasyPay или B-Pay.

Заказы

Статусы заказа

No order yet: покупатель был перенаправлен на ePay.bg и не оплатил, уведомление ещё не пришло или ePay.bg сообщил, что запрос отклонён или истёк. Существует только корзина.

Payment accepted, Delivered or ePay.bg payment on hold: платёж подтверждён. Статус соответствует Order Status After Payment. Платёж записывается с STAN в качестве ID транзакции (или номером счёта, если STAN нет), а примечание показывает номер счёта, дату платежа, STAN и код BORICA.

ePay.bg payment on hold after payment: платёж поступил, но не соответствует тому, что сейчас указано в корзине: сумма или валюта корзины были изменены после платёжного запроса, либо уведомление пришло в другом режиме (тестовом или рабочем), чем запрос. Платёж не регистрируется как оплаченный. То же происходит, если в корзине уже есть неоплаченный заказ, например отменённый или оформленный другим способом оплаты. Примечание объясняет причину. Проверьте платёж в мерчант-панели ePay.bg и вручную выполните заказ или сделайте возврат.

Если платёж поступает для заказа, который уже оплачен или возвращён, статус не меняется, а примечание просит проверить двойной платёж в мерчант-панели ePay.bg. Запоздалое уведомление об отказе или истечении срока никогда не меняет оплаченный заказ.

Блок платежа ePay.bg

На странице заказа показан блок ePay.bg payment со счётом, запрошенными суммой и валютой, результатом уведомления, датой платежа, STAN, кодом BORICA, значком Test mode для тестовых платежей и ePay.bg notes заказа.

Возвраты

Возвраты из PrestaShop недоступны, потому что у WEB API ePay.bg нет вызова возврата. Выполните возврат платежа в мерчант-панели ePay.bg и вручную обновите заказ в PrestaShop.

Лицензионный ключ

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox ePay.bg Gateway — это первый блок на странице Modules > Module Manager > VibeFox ePay.bg Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой лицензия активна, и ваш домен) и кнопки Check now, чтобы снова проверить статус, Change key, чтобы ввести другой ключ, и Remove key, чтобы удалить ключ из этого магазина. Ниже находятся строка Product: presta-payment-epaybg и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт vibefox.net. Изменить ключ могут только сотрудники, имеющие право Configure для модуля. Тексты блока соответствуют языку back office (английский и русский включены).

Если ключ не принят, блок сообщает причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

Один ключ работает на одном домене: домене основного магазина, в том числе в многомагазинной установке. Удаление ключа из магазина не освобождает слот домена. Освободите слот в своём аккаунте vibefox.net.

Без активного ключа ePay.bg не показывается покупателям на этапе оформления заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Витрина PrestaShop не знает, что вы вошли в back office, поэтому способ оплаты скрыт и для вас: модуль можно настроить до покупки ключа, но протестировать на этапе оформления заказа нельзя. Напоминание появляется в разделе Modules > Module Manager на вкладке Alerts. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются.

Когда лицензия истекает, модуль продолжает работать, но обновления и поддержка требуют продления. Статус автоматически проверяется снова, пока вы работаете в back office: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задача не нужна. Удаление или сброс модуля всегда удаляет лицензионный ключ и статус лицензии.

Устранение неполадок

ePay.bg не отображается при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, MIN и секретный ключ выбранного режима заполнены и валюта корзины — BGN, EUR или USD. На странице настроек показывается предупреждение, если учётные данные не заполнены. В Payment > Preferences проверьте, что модуль разрешён для валюты корзины, страны покупателя и группы покупателя.

Платёж прошёл, но заказ не создан: заказ создаётся только уведомлением ePay.bg. Проверьте, что URL уведомлений указан в мерчант-профиле ePay.bg того режима, который вы используете (демо или рабочий), точно так, как показано в Notification URL, и что секретный ключ этого режима верный. Посмотрите поле Log на странице модуля; включите Logging, чтобы видеть каждое уведомление.

Уведомление отвечает ERR=Not valid CHECKSUM: ни один сохранённый секретный ключ не совпадает с мерчант-профилем, который отправил уведомление. ePay.bg продолжает повторять отправку, поэтому заказ будет создан, когда ключ станет верным.

Уведомление отвечает ERR=Not configured: секретный ключ не сохранён. Введите его.

Уведомление отвечает STATUS=NO для счёта: счёт выставлен не этим магазином, например другим магазином на том же аккаунте ePay.bg. Задайте каждому магазину свой Invoice Prefix.

Уведомление отвечает STATUS=ERR: временная ошибка, например два уведомления для одной корзины в один момент или заказ не удалось создать (например, модуль отключён). ePay.bg отправит уведомление повторно. Причина указана в журнале.

URL уведомлений показывает ERR=Method not allowed in the browser: это нормально. URL принимает только запросы от ePay.bg.

Заказ в статусе ePay.bg payment on hold после оплаты: прочитайте примечания в блоке ePay.bg payment (см. Статусы заказа), проверьте платёж в мерчант-панели ePay.bg, затем выполните заказ или сделайте возврат платежа там.

Префикс счёта был изменён при сохранении: префикс может содержать только цифры, до 10. Другие символы удаляются.

Для разработчиков: readme упоминает хук actionEpayBpFormFields (фильтр epay_bp_form_fields версии для WooCommerce), например для использования страницы прямой оплаты картой (PAGE=credit_paydirect).

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox ePay.bg Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete Data on Uninstall включено, настройки шлюза и журнал удаляются. Если выключено, все настройки сохраняются для повторной установки. Записи платежей ePay.bg и статус заказа ePay.bg payment on hold всегда сохраняются, поэтому платёж, начатый до повторной установки, по-прежнему подтверждается. Существующие заказы сохраняют свои платёжные примечания и ID транзакций.

ePay.bg — товарный знак его правообладателя. Этот модуль не связан с ePay.bg и не одобрен ePay.bg.