VibeFox Barion for OpenCart — Помощь

Требования

OpenCart: 3.0.x (проверено на 3.0.5.0).

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

Магазин в Barion: вам нужны POSKey (секретный ключ) вашего магазина и адрес электронной почты кошелька Barion, на который поступают платежи. Оба значения находятся в портале Barion: secure.barion.com для рабочего режима, secure.test.barion.com для тестового, в разделе My stores и в вашем магазине. Тестовые и рабочие данные для входа различаются.

Валюта: валюта заказа должна быть HUF, EUR, USD или CZK. Для других валют способ оплаты скрыт при оформлении заказа.

Доступный магазин: Barion обращается к вашему магазину после каждого платежа, поэтому сайт должен быть доступен из интернета, без межсетевого экрана или базовой аутентификации перед ним. Режим обслуживания не блокирует обратный вызов: OpenCart 3 пропускает запросы расширений оплаты, а на OpenCart 4 расширение добавляет для них стартовое действие (startup action).

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

Установка

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

OpenCart 3

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

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

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

4. Введите тестовый POSKey и адрес электронной почты тестового кошелька, оставьте включённым Test Mode, включите Enable/Disable и нажмите Save. Оформите тестовый заказ.

5. Когда всё заработает, введите рабочие данные и выключите Test Mode.

OpenCart 4

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

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

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

4. Введите лицензионный ключ и данные Barion и проверьте платёж так же, как в шагах с 3 по 5 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях. Отличается только URL обратного вызова (см. Callback URL).

URL обратного вызова автоматически передаётся в Barion с каждым платежом. В портале Barion ничего настраивать не нужно. Новая установка стартует с выключенным способом оплаты и включённым тестовым режимом.

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Barion Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если в текущем режиме не указан POSKey или e-mail получателя (тогда способ оплаты скрывается при оформлении заказа), а также если валюта по умолчанию вашего магазина не поддерживается Barion; приводится список поддерживаемых валют. Пока включён тестовый режим, отображается сообщение Test mode is on: payments go to the Barion sandbox (api.test.barion.com), no real money is charged. Без права изменять расширение страница показывает настройки, но не может их сохранить.

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

Barion

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely with Barion — card, Barion Wallet, Apple Pay or Google Pay.

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

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

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

Данные для входа магазина в Barion

POSKey и e-mail кошелька берутся в портале Barion: secure.barion.com (рабочий режим) или secure.test.barion.com (тестовый), My stores, ваш магазин (порталы указаны ссылками в этом разделе). В тестовом режиме используются только тестовые данные, в рабочем — только рабочие.

Test Mode: использует тестовые данные, указанные ниже, и песочницу Barion (api.test.barion.com). Реальные деньги не списываются. По умолчанию: включено. Выключите, чтобы принимать настоящие платежи. Пока режим включён, покупатели на шаге Confirm Order видят Test mode: no real payment is taken.

Test POSKey: секретный ключ (POSKey) вашего магазина в тестовой системе Barion (secure.test.barion.com, My stores).

Test Payee Email: адрес электронной почты вашего тестового кошелька Barion, на который поступают тестовые платежи.

Live POSKey: секретный ключ (POSKey) вашего магазина в рабочей системе Barion (secure.barion.com, My stores).

Live Payee Email: адрес электронной почты вашего кошелька Barion, на который поступают платежи.

Сохранённые POSKey никогда не отображаются повторно. Поле остаётся пустым и показывает Saved — leave empty to keep it. Вводите новое значение, только если хотите его изменить. Чтобы удалить сохранённый POSKey, отметьте Clear the saved POSKey on save под полем и нажмите Save.

Callback URL: адрес, который Barion вызывает после каждого платежа. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_barion_gateway/callback, в OpenCart 4 так: https://your-store/index.php?route=extension/wcp_barion_gateway/payment/wcp_barion_gateway.callback. Он формируется из публичного адреса вашей установки OpenCart. Он передаётся в Barion с каждым платежом, поэтому ничего настраивать не нужно. Достаточно, чтобы он был доступен из интернета.

Заказы

OpenCart создаёт заказ на шаге Confirm Order без статуса (отсутствующий заказ). Статус он получает только после того, как Barion сообщил о платеже (через обратный вызов или при возврате покупателя; состояние всегда запрашивается у Barion). Каждое поле ниже перечисляет статусы заказов вашего OpenCart.

Order Status After Payment: статус, который ставится после успешного проверенного платежа. По умолчанию: В обработке.

Awaiting Barion Payment Status: покупатель завершил действия на странице Barion, но Barion ещё обрабатывает платёж. По умолчанию: Ожидает оплаты.

Barion Payment On Hold Status: платёж прошёл, но сумма или валюта не совпадают с заказом. Примечание объясняет причину; проверьте платёж вручную. По умолчанию: Ожидает оплаты, так как в OpenCart нет статуса На удержании. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Payment Failed Status: заказ, ожидающий оплаты, платёж Barion по которому не прошёл. По умолчанию: Неудачный.

Payment Canceled Status: заказ, ожидающий оплаты, платёж Barion по которому был отменён или истёк. По умолчанию: Отменён.

Refunded Status: ставится после полного возврата платежа со страницы заказа. По умолчанию: Возвращён.

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

Logging: записывает запросы и обратные вызовы Barion в файл barion_p_debug.log.php в папке логов OpenCart (storage/logs). Открыть файл через веб нельзя. Секретные ключи и e-mail кошельков в журнал не записываются. По умолчанию: выключено. Пока журнал выключен, ничего не записывается, в том числе ошибки.

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

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

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Barion). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to the secure Barion payment page. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение запускает платёж Barion на сумму заказа в валюте заказа и отправляет покупателя на страницу оплаты Barion. В платеже указываются товары, доставка, прочие сборы по заказу и налог; номер заказа OpenCart передаётся как номер заказа, e-mail покупателя передаётся как подсказка, а язык страницы оплаты соответствует языку покупателя, если Barion его поддерживает (венгерский, немецкий, французский, испанский, чешский, словацкий, словенский, греческий, в остальных случаях английский). На OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа.

После оплаты покупатель возвращается в ваш магазин, и Barion также вызывает URL обратного вызова. Ни один из этих запросов сам по себе ничего не отмечает как оплаченное: расширение запрашивает у Barion состояние платежа с POSKey того режима, в котором был начат платёж. Заказ отмечается как оплаченный только после подтверждения Barion и только если сумма и валюта совпадают с заказом. Ссылка возврата содержит случайный токен попытки оплаты, и проверяются только платежи, начатые для этого заказа. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков на складе. На OpenCart 4 браузер не передаёт сессию магазина, когда Barion возвращает покупателя, поэтому расширение сначала показывает короткую страницу, которая открывает тот же адрес возврата заново уже из вашего магазина: покупатель сохраняет корзину и вход в учётную запись.

Если платёж прошёл успешно, покупатель видит страницу успешного оформления заказа OpenCart. Если платёж ещё обрабатывается в Barion, заказу присваивается статус Awaiting Barion Payment Status, а на странице успеха отображается Your payment is being confirmed by Barion. You will receive an e-mail as soon as it is confirmed. Если Barion недоступен при возврате покупателя или платёж совершён, но ещё не применён, страница Payment confirmation показывает тот же текст и кнопку Check again; обратный вызов устанавливает статус заказа, как только Barion подтверждает платёж.

Если платёж не был завершён (отменён, истёк или не прошёл), заказ остаётся без статуса, корзина сохраняется, и покупатель возвращается на оформление заказа с сообщением Payment was not completed. Please try again. Если ссылка возврата не соответствует заказу, выводится сообщение Payment verification failed. На OpenCart 4 эти сообщения показываются над страницей оформления заказа. На OpenCart 3 каждая новая попытка создаёт новый заказ OpenCart. OpenCart 4 хранит один заказ для оформления и обновляет его, поэтому новая попытка — это новый платёж Barion по тому же заказу. Barion не может отменить начатый платёж, поэтому перед новым платежом расширение проверяет в Barion более ранние открытые платежи корзины: если один из них оплачен или ещё обрабатывается, его заказ подтверждается, и покупатель переходит на страницу успеха без повторной оплаты. Если другой заказ из той же корзины (те же товары в том же визите) уже оплачен, покупатель также переходит на страницу успеха без нового платежа; новая покупка после завершённой — это новая корзина. Поздний платёж по более ранней попытке того же заказа всё равно подтверждает его, а более ранняя попытка, которая истекает, заказ не отменяет. Если покупатель всё же оплачивает два заказа одной корзины (две вкладки), второй платёж не подтверждает свой заказ: оплаченный заказ получает примечание о том, что получен второй платёж за ту же корзину, чтобы вы могли вернуть его в портале Barion.

OpenCart 4 хранит заказ на этапе оформления, пока не будет показана страница успешного оформления. Если этот заказ за это время закрылся без оплаты (например, его платёж, ожидавший оплаты, был отменён в Barion или вы отменили заказ), следующее нажатие Confirm Order возвращает покупателя к оформлению заказа с сообщением Payment was not completed. Please try again., и затем оформление создаёт новый заказ из корзины. Если у заказа уже есть статус, а корзина с тех пор изменилась (другие товары или количество), заказ покидает оформление, а изменённая корзина получает новый заказ и свой платёж.

Если платёж не удаётся начать, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой: The Barion payment could not be started. Please try again or choose another payment method., Barion does not support payments in валюта заказа, Barion payment is not available at the moment. Please choose another payment method. или Barion cannot process an order with a zero total. Подробности записываются в журнал, если включено Logging.

Расширение принимает только немедленные платежи. Оно не поддерживает платежи с резервированием или отложенным списанием, подписки и периодические платежи, сохранённые карты, Barion Pixel и дополнительные данные 3-D Secure; 3-D Secure обрабатывает Barion на своей странице оплаты.

Заказы и возвраты

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

Нет статуса (отсутствующий заказ): покупатель был перенаправлен в Barion и не оплатил, платёж не был завершён или Barion ещё не подтвердил платёж. В Sales > Orders такие заказы показываются только при фильтре Order Status, установленном в Missing Orders.

Awaiting Barion Payment Status (по умолчанию Pending): Barion сообщает, что платёж ещё обрабатывается. Примечание показывает PaymentId Barion, сумму и, в тестовом режиме, (test mode). Заказ переходит в оплаченный статус, когда Barion подтверждает платёж.

Order Status After Payment (по умолчанию Processing): Barion подтвердил платёж. Примечание показывает сумму, PaymentId и транзакцию Barion.

Barion Payment On Hold Status (по умолчанию Pending): Barion сообщил сумму или валюту, отличающиеся от суммы заказа. Примечание показывает обе суммы. Проверьте платёж в портале Barion, затем выполните заказ или верните платёж в портале Barion.

Payment Canceled Status (по умолчанию Canceled): последняя попытка платежа ожидающего заказа была отменена или истекла в Barion.

Payment Failed Status (по умолчанию Failed): последняя попытка платежа ожидающего заказа не прошла.

Refunded Status (по умолчанию Refunded): платёж полностью возвращён через расширение.

Если платёж по заказу всё же проходит после отмены или сбоя заказа, заказ становится оплаченным. Оплаченный или возвращённый заказ никогда не изменяется последующим обратным вызовом. Если для уже оплаченного заказа проходит другой платёж, примечание просит вас проверить его в портале Barion и вернуть, если это дубликат. Примечания — это записи в History заказа, которые покупатель не видит.

Вкладка VibeFox Barion Gateway

В Sales > Orders откройте заказ, оплаченный через Barion. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Barion Gateway показывает PaymentId с меткой Test mode для тестовых платежей, Transaction Barion, Status платежа, суммы Paid / refunded, форму возврата, историю возвратов и Barion notes заказа. Вкладка показывается пользователям, имеющим доступ к расширению.

Возвраты

На вкладке VibeFox Barion Gateway введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости Reason (optional) и нажмите Refund via Barion. Подтвердите вопрос Вернуть эту сумму через Barion? Это действие нельзя отменить. Поддерживаются полный и частичный возврат. Вам нужно право изменять расширение (задаётся в System > Users > User Groups). Причина передаётся в Barion как комментарий. Возвраты в HUF должны быть на целые суммы. Возврат отправляется в том режиме (тестовом или рабочем), в котором был совершён платёж, поэтому POSKey этого режима должен быть задан. Если Barion не принимает или не подтверждает возврат, вкладка показывает ошибку, и возврат не регистрируется. Успешный возврат добавляется в историю возвратов и примечания вместе с транзакцией и статусом Barion. Полный возврат устанавливает заказу Refunded Status без уведомления покупателя и без возврата товаров на склад, как и при ручном изменении статуса. Частичный возврат статус не меняет.

Возвраты доступны, когда Barion подтвердил платёж и заказ оплачен им. Платёж с расхождением суммы или валюты нельзя вернуть из OpenCart; верните его в портале Barion. Возвраты товаров в Sales > Returns деньги через Barion не возвращают.

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

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

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

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

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

Barion не появляется при оформлении заказа: проверьте, что лицензия активна, Enable/Disable включено, в текущем режиме указаны POSKey и e-mail получателя (на странице настроек появляется предупреждение, если чего-то не хватает), а валюта заказа — HUF, EUR, USD или CZK. Также проверьте, что платёжный адрес входит в выбранную Geo Zone, и что сумма заказа достигает значения Total, заданного в настройках.

Платёж прошёл, но заказ остаётся без статуса: заказ получает статус, когда Barion вызывает URL обратного вызова или когда покупатель возвращается в ваш магазин. Убедитесь, что сайт доступен из интернета (без межсетевого экрана или базовой аутентификации перед URL обратного вызова). Проверьте, что POSKey того режима, в котором был совершён платёж, указан верно, поскольку расширение запрашивает у Barion состояние платежа с его помощью. Включите Logging, чтобы увидеть обратный вызов.

Обратный вызов отвечает Busy, retry: заказ в тот же момент обрабатывался при возврате покупателя, либо не удалось установить статус заказа. Barion вызовет снова. Включите Logging, чтобы увидеть причину.

Обратный вызов отвечает API error: магазин не смог получить состояние платежа из Barion либо не задан POSKey того режима, в котором был совершён платёж. Проверьте этот POSKey.

Обратный вызов отвечает Order not found: PaymentId не был начат этим магазином. Вызовы Barion для других магазинов или тестовых систем игнорируются.

Покупатель видит Payment verification failed.: ссылка возврата не соответствует заказу, например, она была изменена. Состояние платежа всё равно подтверждается обратным вызовом.

Покупатель видит ошибку после Confirm Order: включите Logging и посмотрите поле Log на странице расширения. Неверный POSKey или e-mail получателя дают сообщение The Barion payment could not be started. This payment method is not available. Please reload the checkout page. означает, что сессия оформления больше не соответствует заказу или способ оплаты тем временем выключили: покупатель должен перезагрузить страницу оформления заказа.

Заказ находится в статусе удержания: прочитайте примечание о расхождении на вкладке VibeFox Barion Gateway, проверьте платёж в портале Barion, затем выполните заказ или верните платёж в портале Barion.

Почему нельзя вернуть 10.50 HUF: Barion обрабатывает HUF без десятичных знаков. Введите целую сумму.

На вкладке нет формы возврата: вкладка указывает причину: платёж ещё не подтверждён, он полностью возвращён, ваша группа пользователей не имеет права изменять расширение, или не настроен POSKey режима платежа.

Для разработчиков: расширение вызывает события OpenCart wcp_barion_supported_currencies (список валют) и wcp_barion_payment_request (запрос платежа и заказ до отправки в Barion).

Удаление

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

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

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