VibeFox Barion for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

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

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

Доступный магазин: Barion обращается к вашему магазину после каждого платежа, поэтому сайт должен быть доступен из интернета, без межсетевого экрана или базовой аутентификации перед ним.

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

Установка

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

2. Когда загрузка завершится, нажмите Configure или позже найдите VibeFox Barion Gateway в списке модулей и нажмите Configure.

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

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

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

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

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

Настройка

Все настройки находятся на странице модуля: Modules > Module Manager > VibeFox Barion Gateway > Configure. У каждого раздела есть своя кнопка Save, которая сохраняет всю страницу. Над полями страница предупреждает, если в текущей среде нет POSKey или e-mail получателя (тогда способ оплаты скрыт на этапе оформления заказа), и если основная валюта магазина не поддерживается Barion — с перечнем поддерживаемых валют. Пока включён тестовый режим, отображается сообщение Тестовый режим включён: платежи направляются в песочницу Barion (api.test.barion.com), реальные деньги не списываются.

Barion

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

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

Description: текст под способом оплаты на этапе оформления заказа. По умолчанию: Pay securely with Barion — card, Barion Wallet, Apple Pay or Google Pay.

Учётные данные магазина Barion

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

Test Mode: использует тестовые учётные данные, указанные ниже, и песочницу Barion (api.test.barion.com). Реальные деньги не списываются. По умолчанию: включено. Выключите его, чтобы принимать реальные платежи. Пока он включён, покупатели видят под способом оплаты сообщение Тестовый режим: реальный платёж не производится.

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

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

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

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

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

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

Callback URL: адрес, который Barion вызывает после каждого платежа, например https://your-shop/module/wcp_barion_gateway/callback при включённых понятных URL, возможно с кодом языка, например /en/. Он отправляется в Barion с каждым платежом, поэтому ничего настраивать не нужно. Достаточно, чтобы он был доступен из интернета.

Заказы

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

Платежи, которые Barion ещё обрабатывает, ожидают в статусе Awaiting Barion payment. Несовпадения суммы или валюты всегда переводят заказ в Barion payment on hold.

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

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

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

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

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Barion) и видит примечание Вы будете перенаправлены на защищённую страницу оплаты Barion. После подтверждения модуль создаёт платёж Barion на сумму корзины в валюте корзины и отправляет покупателя на страницу оплаты Barion. Товары, доставка, подарочная упаковка и налог перечисляются в платеже, платёж отображается как Cart с номером корзины, e-mail покупателя передаётся как подсказка, а язык страницы следует за языком корзины, если Barion его поддерживает. На этом этапе заказа ещё не существует.

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

Если платёж прошёл успешно, заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа с сообщением Ваш платёж через Barion получен. Если платёж ещё обрабатывается в Barion, заказ создаётся в статусе Awaiting Barion payment, а страница показывает Ваш платёж подтверждается Barion. Вы получите письмо, как только он будет подтверждён. Если такой платёж позже отменён, истёк или не прошёл в Barion, страница показывает Ваш платёж через Barion не был завершён. Пожалуйста, свяжитесь с нами по поводу этого заказа. Если Barion недоступен, когда покупатель возвращается, появляется страница Подтверждение платежа с тем же текстом «подтверждается» и кнопкой Check again; колбэк создаст заказ, как только Barion подтвердит платёж.

Если платёж не был завершён (отменён, истёк или не прошёл), заказ не создаётся, корзина сохраняется, и покупатель возвращается к оформлению заказа с сообщением Оплата не была завершена. Пожалуйста, попробуйте снова. Покупатель может повторить попытку. Каждая попытка запоминается, поэтому поздний платёж по более ранней попытке всё равно создаёт заказ, а истёкшая более ранняя попытка не отменяет заказ более новой попытки.

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

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

Модуль принимает только немедленные платежи. В нём нет платежей с резервированием или отложенным списанием, подписок и регулярных платежей, сохранённых карт, Barion Pixel и дополнительных данных 3-D Secure; 3-D Secure обрабатывает Barion на своей странице оплаты.

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

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

No order yet: покупатель был перенаправлен в Barion и не оплатил или Barion ещё не подтвердил платёж. Существует только корзина.

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

Payment accepted or Delivered: Barion подтвердил платёж. Статус следует за Order Status After Payment. Платёж фиксируется с идентификатором транзакции Barion, а примечание показывает сумму, PaymentId и транзакцию.

Barion payment on hold: Barion сообщил сумму или валюту, отличающиеся от суммы заказа, например потому, что корзина была изменена после начала платежа. Примечание показывает обе суммы. Проверьте платёж в портале Barion, затем выполните заказ или сделайте возврат платежа в портале Barion.

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

Payment error: последняя попытка оплаты ожидающего заказа не удалась.

Refunded: платёж полностью возвращён через модуль.

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

Блок оплаты Barion

На странице заказа отображается блок Barion payment с PaymentId, транзакцией Barion, статусом платежа, оплаченной и возвращённой суммой, значком Test mode для тестовых платежей и историей возвратов.

Возвраты

В блоке Barion payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости причину, и нажмите Refund via Barion. Подтвердите вопрос Вернуть эту сумму через Barion? Это действие нельзя отменить. Поддерживаются полные и частичные возвраты. Нужно право на редактирование заказов. Причина отправляется в Barion как комментарий. Возвраты в HUF должны быть целыми суммами. Возврат отправляется в той среде (тестовой или рабочей), в которой был сделан платёж, поэтому POSKey этой среды должен быть заполнен. Если Barion не принимает или не подтверждает возврат, блок показывает ошибку, и возврат не фиксируется. Успешный возврат добавляется в историю возвратов и примечания с транзакцией и статусом Barion. Полный возврат переводит заказ в статус Refunded. Частичный возврат статус не меняет.

Возвраты доступны, когда Barion подтвердил платёж и заказ оплачен через него. Платёж с несовпадением суммы или валюты нельзя вернуть из PrestaShop — верните его в портале Barion. Модуль не создаёт кредитовых авизо, а стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Barion.

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

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

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

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

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

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

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

Колбэк отвечает Busy, retry: заказ в этот момент обрабатывался при возврате покупателя или заказ не удалось создать (например, модуль отключён). Barion повторит вызов. Включите Logging, чтобы увидеть причину.

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

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

Покупатель видит «Ошибка проверки платежа»: ссылка возврата не соответствует корзине, например её открыли в другом сеансе браузера или изменили. Состояние платежа всё равно подтверждается колбэком.

Покупатель видит ошибку при выборе Barion: включите Logging и посмотрите поле Log на странице модуля. Неверный POSKey или e-mail получателя приводит к сообщению Не удалось начать платёж через Barion.

Заказ в статусе Barion payment on hold: прочитайте примечание о несовпадении в заказе, проверьте платёж в портале Barion, затем выполните заказ или верните его в портале Barion.

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

Возврат сообщает, что POSKey Barion для среды этого заказа не настроен: платёж был сделан в тестовой или рабочей среде, а POSKey этой среды пуст. Введите его и повторите попытку.

Удаление

Перейдите в Modules > Module Manager, откройте меню рядом с VibeFox Barion Gateway и выберите Uninstall. Лицензионный ключ и статус лицензии этого модуля всегда удаляются. Если Delete Data on Uninstall включено, настройки модуля и журнал удаляются. Если выключено, все настройки сохраняются для последующей переустановки. Данные об оплате Barion по заказам и статусы заказов Awaiting Barion payment и Barion payment on hold всегда сохраняются, поэтому заказы, оплаченные ранее, можно вернуть и после переустановки. Существующие заказы сохраняют свои примечания об оплате и идентификаторы транзакций.

Barion является товарным знаком своего правообладателя. Этот модуль не аффилирован с Barion и не одобрен Barion.