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

Требования

WordPress: 6.0 или новее.

WooCommerce: 7.0 или новее, установлен и активен.

PHP: 8.0 или новее.

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

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

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

Установка

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

2. Нажмите Activate. WooCommerce должен быть активен.

3. Откройте настройки: WooCommerce > Settings > Payments > ePay.bg > Manage, или нажмите Settings под названием плагина на странице плагинов.

4. Введите лицензионный ключ VibeFox в блоке лицензии вверху страницы и нажмите Activate.

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

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

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

Настройка

Все настройки находятся на одной странице: WooCommerce > Settings > Payments > ePay.bg. Над полями страница показывает ошибку, если валюта магазина не 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: Enable test mode (use demo.epay.bg and the test credentials). Когда режим включён, покупатели перенаправляются в демо-среду 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.

Если вы обновляетесь с версии 1.0, единственный набор учётных данных этой версии переносится в тестовые поля, если был включён тестовый режим.

Уведомления об оплате (IPN)

Уведомление сообщает вашему магазину, что платёжный запрос оплачен, отклонён или истёк. В этом разделе показан URL уведомлений. Он выглядит так: https://your-site/wc-api/epaybg_payment_callback/. Укажите его как URL for receiving notifications в мерчант-профиле ePay.bg — рабочем и тестовом. Заказы отмечаются оплаченными только по этим подписанным уведомлениям; возврат покупателя в магазин не отмечает заказ оплаченным.

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

Каждое уведомление проверяется секретным ключом выбранного режима. Уведомления без действительной контрольной суммы отклоняются, и ePay.bg продолжает их отправлять. Если URL уведомлений не указан в мерчант-профиле, ни один заказ не будет отмечен оплаченным.

Платёжный запрос

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: статус заказа, который устанавливается после успешной оплаты. Статус устанавливается сразу, без повторной смены статуса.

Дополнительно

Logging: Enable logging записывает платёжные запросы и уведомления в WooCommerce > Status > Logs, источник wcp_epaybg_gateway, без секретных ключей и данных карт. По умолчанию: выключено.

Delete Data on Uninstall: Remove all plugin data when uninstalled. Если флажок установлен, при удалении плагина удаляются настройки шлюза, данные ePay.bg, сохранённые в заказах, и журналы плагина. По умолчанию: выключено.

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

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

После оплаты покупатель возвращается на страницу «Заказ принят» вашего магазина. Заказ отмечается оплаченным только тогда, когда приходит подписанное уведомление ePay.bg. Корзина очищается только на странице «Заказ принят».

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

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

Способ оплаты работает в классическом оформлении заказа, в блоке «Оформление заказа» и на странице Pay for order. Он совместим с высокопроизводительным хранилищем заказов WooCommerce (HPOS).

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

Заказы

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

Pending payment: покупатель отправлен на ePay.bg и ещё не оплатил, либо уведомление ещё не пришло. В заметке к заказу указано Awaiting ePay.bg payment.

Processing, Completed or On Hold: платёж подтверждён. Статус определяется настройкой Order Status After Payment. В заметке к заказу указаны номер счёта, дата платежа, STAN и код BORICA. ID транзакции — это STAN (или номер счёта, если STAN нет).

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

Cancelled: ePay.bg сообщил, что платёжный запрос отклонён или истёк, либо покупатель отменил оплату на ePay.bg. WooCommerce возвращает остатки на склад. Отменённый заказ нельзя оплатить повторно, потому что номер счёта ePay.bg — это префикс плюс ID заказа. Покупатель оформляет новый заказ.

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

Возвраты

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

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

Плагин работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии находится вверху страницы WooCommerce > Settings > Payments > ePay.bg. Вставьте ключ в поле License key и нажмите Activate. В блоке показан статус, например дата, до которой действует лицензия, и ваш домен. Кнопка Check now повторно проверяет статус, Change key позволяет ввести другой ключ, а Remove key удаляет его с этого сайта. Ссылка Manage licenses and domains in your account открывает ваш аккаунт на vibefox.net.

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

Без активного ключа ePay.bg не показывается покупателям при оформлении заказа. Если платёж всё же начат, покупатель видит сообщение This payment method is not available. Please choose another one. Вошедшие в систему менеджеры магазина по-прежнему видят способ оплаты с пометкой (unlicensed — visible to admins only), так что вы можете настроить и протестировать плагин до покупки ключа. Напоминание появляется на странице плагинов и на страницах WooCommerce. Существующие заказы не затрагиваются: уже начатые платежи по-прежнему подтверждаются.

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

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

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

Платёж прошёл, но заказ остаётся «Ожидает оплаты»: заказ отмечается оплаченным только по уведомлению ePay.bg. Проверьте, что URL уведомлений указан в мерчант-профиле ePay.bg того режима, который вы используете (демо или рабочий), и что секретный ключ активного режима верный. Включите Logging и посмотрите WooCommerce > Status > Logs, источник wcp_epaybg_gateway.

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

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

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

Уведомление отвечает STATUS=ERR: временная ошибка, например два уведомления по одному заказу в один и тот же момент. ePay.bg отправляет уведомление повторно.

После оплаты заказ «На удержании»: прочитайте заметку к заказу. Сумма или валюта изменились после платёжного запроса, запрос был сделан в другом режиме либо режим потом переключили, изменился способ оплаты или заказ был отменён. Проверьте платёж в мерчант-панели ePay.bg.

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

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

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

Удаление

Деактивация плагина сохраняет все данные. Чтобы удалить его, деактивируйте и удалите плагин на странице Plugins. Лицензионный ключ и статус лицензии этого плагина удаляются всегда. Настройки шлюза, данные ePay.bg, сохранённые в заказах, и журналы удаляются, только если был включён Delete Data on Uninstall. В противном случае они остаются для последующей переустановки. Существующие заказы сохраняют свои заметки об оплате и ID транзакций.

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