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

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).

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

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

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

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

Установка

Скачиваемый архив — это один zip-файл с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_epaybg_gateway-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_epaybg_gateway.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаков для обеих версий.

OpenCart 3

1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_epaybg_gateway-oc3-(version).ocmod.zip. Расширение не содержит модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload из этого пакета в корневую папку вашего магазина.

2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox ePay.bg Gateway и нажмите Install (зелёная кнопка +). Вашему административному пользователю нужно право изменять список расширений оплаты.

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

4. Введите MIN и секретный ключ для тестового и/или боевого режима (см. Конфигурация).

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

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

OpenCart 4

1. В административной части перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_epaybg_gateway.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.

2. Пакет появится в списке установленных расширений на той же странице. Нажмите Install (зелёная кнопка +) рядом с ним.

3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox ePay.bg Gateway, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).

4. Введите лицензионный ключ, учётные данные ePay.bg и URL уведомления, как в шагах 3–6 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только URL уведомления (см. Уведомления об оплате (IPN)).

Новая установка начинается с выключенным способом оплаты и включённым тестовым режимом.

Конфигурация

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

При сохранении Title не может быть пустым (до 128 символов), Sort Order должно быть целым числом, а Total — числом не меньше 0; если какое-либо поле заполнено неверно, ничего не сохраняется.

ePay.bg

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

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

Description: текст, который показывается покупателю на шаге Confirm Order. По умолчанию: Pay securely via ePay.bg with a bank card or your ePay.bg account.

Sort Order: позиция ePay.bg среди способов оплаты при оформлении заказа. Оставьте поле пустым или введите целое число.

Geo Zone: предлагать ePay.bg только для платёжных адресов в выбранной географической зоне. По умолчанию: All zones. Географические зоны настраиваются в разделе System > Localisation > Geo Zones.

Total: сумма заказа в валюте магазина по умолчанию, которую заказ должен достичь, прежде чем будет предложен ePay.bg. Оставьте поле пустым, чтобы предлагать ePay.bg при любой сумме.

Учётная запись ePay.bg

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

Test Mode: включает тестовый режим. Покупатели перенаправляются в демонстрационную среду ePay.bg, а запросы подписываются тестовыми учётными данными. По умолчанию: включено. Пока он включён, покупатели видят на шаге Confirm Order сообщение Test mode (demo.epay.bg): no real payment is taken.

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 the saved key on save под полем и нажмите Save. Пробелы и переносы строк во вставленных ключах удаляются при сохранении.

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

Уведомление сообщает вашему магазину, что запрос на оплату оплачен, отклонён или истёк срок его действия. Поле Notification URL показывает URL, который нужно указать как URL for receiving notifications в профиле мерчанта ePay.bg — боевом и демонстрационном. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_epaybg_gateway/notify, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_epaybg_gateway/payment/wcp_epaybg_gateway.notify. Он формируется из адреса витрины вашей установки OpenCart. Скопируйте URL точно так, как он показан в настройках. Заказы получают статус только по этим подписанным уведомлениям; покупатель, вернувшийся в магазин, не оплачивает заказ.

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

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

Запрос на оплату

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

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

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

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Он получает статус только тогда, когда ePay.bg сообщает об оплате. Отклонённый, истёкший или брошенный платёж оставляет заказ без статуса, и покупатель может оплатить снова. Поля статусов ниже перечисляют статусы заказов вашего OpenCart.

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

Processing status: статус OpenCart для Default и Processing. По умолчанию: Processing.

Completed status: статус OpenCart для Completed. По умолчанию: Complete.

On Hold status: статус OpenCart для On Hold и для платежей, требующих ручной проверки: сумма заказа или валюта изменились после запроса на оплату, уведомление пришло в другом режиме или статус заказа был изменён до поступления платежа (например, отменён). Такой заказ не отмечается оплаченным; примечание объясняет причину. По умолчанию: Pending, так как в OpenCart нет статуса On hold. Вы можете создать свой статус в разделе System > Localisation > Order Statuses и выбрать его здесь.

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

Logging: записывает запросы на оплату и уведомления в файл epay_bp_debug.log.php в папке логов OpenCart (storage/logs). Файл нельзя открыть через веб; при достижении 5 МБ он переносится в epay_bp_debug.old.log.php. Секретные ключи и данные карт не записываются. По умолчанию: выключено. Ошибки записываются всегда, даже когда этот параметр выключен.

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

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

Импорт / Экспорт

Export: Download JSON сохраняет настройки в файл JSON. Секретные ключи не экспортируются.

Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые секретные ключи сохраняются.

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию ePay.bg). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to ePay.bg to pay with a bank card or your ePay.bg account. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Когда покупатель нажимает Confirm Order, расширение отправляет его в ePay.bg с подписанным запросом на оплату на сумму заказа в валюте заказа, с номером счёта и сроком действия. Платёж отображается в ePay.bg как Order с номером заказа. В ePay.bg покупатель платит банковской картой или через учётную запись ePay.bg.

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после того, как ePay.bg подтверждает платёж подписанным уведомлением. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков. Если уведомление уже пришло, покупатель видит страницу успешного оформления заказа OpenCart. Если нет, страница Payment confirmation сообщает: Thank you. Your payment is being confirmed by ePay.bg — your order is confirmed as soon as ePay.bg reports the payment. с кнопками 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. На OpenCart 4 эти сообщения выводятся над страницей оформления заказа. Корзина сохраняется. Новая попытка для того же заказа использует тот же номер счёта. OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; OpenCart 4 обновляет заказ оформления, поэтому новая попытка оплачивает тот же заказ с новым платёжным запросом. Если другой заказ из той же корзины уже оплачен, покупатель переходит на страницу успешного оформления, и новая оплата не начинается.

OpenCart 4 хранит заказ в оформлении до показа страницы успеха. Если этот заказ тем временем был закрыт без оплаты (например, вы его отменили), покупатель возвращается на оформление заказа с сообщением Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., а следующий Confirm Order оплачивает новый заказ корзины. Если заказ уже оплачен, а корзина с тех пор изменилась, в том числе новым количеством, покупатель возвращается на оформление заказа, и следующий Confirm Order оплачивает новую корзину новым заказом. Оплаченный заказ никогда не показывается как оплаченный для другой корзины.

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

Уведомление работает и тогда, когда магазин находится в режиме обслуживания: OpenCart 3 пропускает запросы расширений оплаты, а на OpenCart 4 расширение добавляет стартовое действие (startup action) для уведомления. Уведомления о платежах, которые уже начаты, принимаются, даже если вы выключили способ оплаты.

Расширение принимает только разовые платежи через ePay.bg. Оно не поддерживает возвраты из OpenCart, сохранённые карты, подписки или периодические платежи, а также наличные платёжные коды EasyPay или B-Pay.

Заказы

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

No status (missing order): покупатель был отправлен в ePay.bg и не оплатил, уведомление ещё не пришло или ePay.bg сообщил, что запрос отклонён или истёк. В разделе Sales > Orders такие заказы показываются только с фильтром Order Status, установленным на Missing Orders.

Processing, Completed или On Hold status: платёж подтверждён. Статус следует за Order Status After Payment. Примечание показывает номер счёта, дату платежа, STAN и код BORICA.

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

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

Примечания — это записи в History заказа, которые покупатель не видит.

Вкладка VibeFox ePay.bg Gateway

В разделе Sales > Orders откройте заказ, оплаченный через ePay.bg. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox ePay.bg Gateway показывает счёт, среду (тестовую или боевую) с меткой Test mode для тестовых платежей, запрошенную сумму и валюту, состояние запроса на оплату, результат уведомления, дату платежа, STAN, код BORICA и ePay.bg notes заказа. Вкладка доступна только для чтения и показывается пользователям, имеющим доступ к расширению.

Возвраты

Возвраты из OpenCart недоступны, так как в WEB API ePay.bg нет вызова для возврата. Верните платёж в панели мерчанта ePay.bg и вручную обновите статус заказа в OpenCart. Возвраты товаров в разделе Sales > Returns не возвращают деньги через ePay.bg.

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

Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox ePay.bg Gateway — это первый блок в разделе Extensions > Extensions > Payments > VibeFox ePay.bg Gateway > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой действует лицензия, и ваш домен), а также кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-payment-epaybg и ссылка 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.

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

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

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

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

Платёж прошёл, но заказ остаётся без статуса: заказ получает статус только из уведомления 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.

Покупатель видит This payment method is not available. Please reload the checkout page.: сессия оформления заказа больше не соответствует заказу или способ оплаты тем временем был выключен. Покупатель должен перезагрузить страницу оформления заказа.

Покупатель видит This order has nothing to pay.: сумма заказа равна нулю, поэтому отправлять в ePay.bg нечего.

Заказ в статусе On Hold после оплаты: прочитайте примечания на вкладке VibeFox ePay.bg Gateway (см. Статусы заказов), проверьте платёж в панели мерчанта ePay.bg, затем выполните заказ или верните платёж там.

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

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

Удаление

Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox ePay.bg Gateway. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable/Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Orders, которые при повторной установке возвращаются к значениям по умолчанию. На OpenCart 4 удаляются также событие расширения (сообщение при оформлении заказа) и его стартовое действие, которое пропускает уведомление в режиме обслуживания. Если Delete Data on Uninstall включено, удаляются остальные настройки шлюза (название, описание, тестовый режим, MIN и секретные ключи, запрос на оплату, статус после оплаты, журналирование) и журнал. Если выключено, они сохраняются для последующей повторной установки. Записи платежей ePay.bg всегда сохраняются, поэтому платёж, начатый до повторной установки, по-прежнему подтверждается. Существующие заказы сохраняют свои примечания об оплате.

На OpenCart 4, чтобы удалить также файлы расширения, после удаления перейдите в Extensions > Installer, нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox ePay.bg Gateway в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.

ePay.bg — торговая марка её владельца. Это расширение не связано с ePay.bg и не одобрено ePay.bg.