VibeFox MultiSafepay for OpenCart — Помощь

Требования

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

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

Валюта: валюта оформления заказа должна быть одной из тех, которые принимает MultiSafepay, например EUR, USD, GBP, PLN, CHF, SEK, DKK или NOK. Для других валют способ оплаты скрывается при оформлении заказа.

Учётная запись MultiSafepay: вам нужен API-ключ вашего сайта в MultiSafepay Control. У тестовой и боевой учётных записей разные ключи. Больше ничего в MultiSafepay настраивать не нужно: адрес уведомлений передаётся с каждым платежом.

Публичный сайт: MultiSafepay должен иметь доступ к вашему магазину, чтобы отправлять уведомления. Иначе заказы всё равно получат статус, когда покупатель вернётся из MultiSafepay.

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

Установка

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

OpenCart 3

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

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

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

4. Вставьте тестовый и/или боевой API-ключ из MultiSafepay Control (см. Configuration).

5. Включите Enable/Disable и нажмите Save. Проверьте оплату с включённым Test mode, затем выключите его, чтобы принимать настоящие платежи.

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox MultiSafepay Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница показывает Test mode: new payments use the MultiSafepay test environment (no real payments)., пока включён тестовый режим, предупреждает, если способ оплаты включён, но у текущего режима нет API-ключа (тогда способ оплаты не показывается при оформлении заказа), и если MultiSafepay не принимает валюту магазина по умолчанию. Без права изменять расширение страница показывает настройки, но не может их сохранить.

При сохранении Title должен содержать от 1 до 128 символов, Sort Order должен быть целым числом (отрицательные значения допустимы), Total должен быть числом не меньше 0, а геозона и статусы заказов должны существовать. Иначе ничего не сохраняется, и страница называет проблему. Если способ оплаты включён без API-ключа текущего режима, настройки сохраняются с предупреждением.

Checkout

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

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

Description: текст, который показывается покупателю на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely with iDEAL, cards, Bancontact, PayPal and more via MultiSafepay.

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

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

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

API-ключи

API-ключ находится в разделе MultiSafepay Control > Manage settings > Website settings. Раздел содержит ссылки на тестовую учётную запись (testmerchant.multisafepay.com) и боевую учётную запись (merchant.multisafepay.com). У них разные ключи. Тестовый режим использует только тестовый ключ, боевой режим — только боевой.

Test mode: использует тестовую среду MultiSafepay (без настоящих платежей). Переключаются и адрес API, и API-ключ. Уже выполненные платежи для проверки статуса и возвратов продолжают использовать ту среду, в которой были сделаны. По умолчанию: включено. Пока режим включён, на шаге Confirm Order покупатель видит Test mode: no real payment will be made.

Test API key: API-ключ вашей тестовой учётной записи MultiSafepay.

Live API key: API-ключ вашей боевой учётной записи MultiSafepay.

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

Уведомления

Ничего настраивать не нужно. Поле Notification URL показывает адрес, который передаётся в MultiSafepay с каждым платежом. В OpenCart 3 он выглядит так: https://your-store/index.php?route=extension/payment/wcp_multisafepay_gateway/webhook, в OpenCart 4 — так: https://your-store/index.php?route=extension/wcp_multisafepay_gateway/payment/wcp_multisafepay_gateway.webhook. Он формируется из адреса витрины вашей установки OpenCart. Уведомление лишь сообщает расширению, какой платёж изменился: статус, сумма и валюта всегда запрашиваются из API MultiSafepay с API-ключом среды платежа, прежде чем заказ меняется. Уведомления о платежах, которые не были начаты в вашем магазине, игнорируются. Уведомление работает и тогда, когда магазин находится в режиме обслуживания, потому что OpenCart 3 пропускает запросы расширений оплаты, а в OpenCart 4 расширение добавляет для этого стартовое действие, которое также позволяет покупателю вернуться из MultiSafepay.

Заказы

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

Order status after payment: статус оплаченного заказа. По умолчанию: В обработке. Выберите Complete, чтобы сразу завершать оплаченные заказы.

MultiSafepay payment on hold status: платёж требует вашего внимания (см. Order statuses). По умолчанию: Ожидание, так как в OpenCart нет статуса На удержании. Вы можете создать собственный статус в System > Localisation > Order Statuses и выбрать его здесь.

Payment error status: непроведённый или зарезервированный платёж был впоследствии отклонён, истёк или отменён. По умолчанию: Не удался.

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

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

Debug log: записывает вызовы API и уведомления в mspg_debug.log.php в папке журналов OpenCart (storage/logs). Файл нельзя открыть через веб. Ошибки и предупреждения записываются всегда. API-ключи и данные покупателей никогда не записываются. По умолчанию: выключено.

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

Delete data on uninstall: если включено, при удалении расширения удаляются настройки шлюза и журнал. Платёжные данные MultiSafepay по заказам всегда сохраняются, поэтому возвраты по старым заказам остаются возможными. Отключение расширения ничего не удаляет. По умолчанию: выключено.

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

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

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

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

На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию MultiSafepay). На шаге Confirm Order покупатель видит ваше описание и примечание You will be redirected to MultiSafepay to choose a payment method and pay. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение создаёт платёж MultiSafepay на сумму заказа в валюте заказа и отправляет покупателя на страницу оплаты MultiSafepay. Там покупатель выбирает любой способ оплаты, включённый в вашей учётной записи MultiSafepay, и платит. В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options, и нажимает Confirm Order внизу страницы оформления заказа. Платёжный адрес, e-mail, телефон и язык покупателя передаются в MultiSafepay, а платёж отображается как Order #, номер заказа и название вашего магазина.

После оплаты покупатель возвращается в ваш магазин. Заказ помечается оплаченным только после подтверждения MultiSafepay: уведомлением или проверкой через API MultiSafepay при возврате покупателя. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart с сообщением Your payment with MultiSafepay has been received. Для заказа на удержании страница показывает We are confirming your payment with MultiSafepay. The order will be updated automatically — please do not pay again. Если платёж позже не прошёл, страница показывает Your MultiSafepay payment was not completed. Please contact us about this order. Если MultiSafepay ещё не подтвердил платёж к моменту возврата покупателя (например, ожидается банковский перевод), страница Payment confirmation показывает тот же текст «мы подтверждаем оплату» и кнопку Check again; уведомление устанавливает статус заказа, как только MultiSafepay сообщает о платеже.

Если покупатель отменяет оплату на странице MultiSafepay или платёж отклонён либо истёк, он возвращается к оформлению заказа с сохранённой корзиной и одним из сообщений: The MultiSafepay payment was cancelled. You can try again or choose another payment method., The payment was declined. Please try again or choose another payment method. или The payment session has expired. Please try again. В OpenCart 4 эти сообщения показываются над страницей оформления заказа.

OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, а OpenCart 4 хранит один заказ на время оформления и при повторной оплате использует тот же заказ. Прежде чем создать новый платёж, расширение проверяет в MultiSafepay предыдущие платежи той же корзины. Если один из них уже оплачен или обрабатывается, он подтверждается, и покупатель переходит на страницу успеха, а не платит снова. Если платёж этого заказа всё ещё открыт с той же средой, суммой и валютой, используется та же страница оплаты. Иначе старый платёж отменяется в MultiSafepay, чтобы его больше нельзя было оплатить.

OpenCart 4 хранит заказ оформления до показа страницы успеха. Если этот заказ тем временем был закрыт без оплаты (например, его платёж был отклонён или истёк после перевода на удержание, либо вы его отменили), покупатель возвращается к оформлению заказа с сообщением Your previous order was cancelled without a payment. Please confirm the order again to pay with a new order., и следующее нажатие Confirm Order оплачивает новый заказ. Если заказ был оплачен, а затем закрыт магазином (например, возвращён), сообщение: Your previous order #(номер) was closed by the store. Please confirm the order again to pay with a new order. Если заказ оформления уже размещён, а корзина с тех пор изменилась, сообщение: Your previous order #(номер) has already been placed. Your cart has changed: please confirm the new order to pay for it. Любое изменение корзины, включая новое количество, считается новой корзиной, которой нужна собственная оплата. Оплаченный, а затем отменённый или возвращённый заказ больше не удерживает корзину.

Если MultiSafepay не может начать платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, например Could not connect to MultiSafepay. Please try again in a moment. или MultiSafepay cannot accept this order amount or currency. Please choose another payment method. Техническая причина записывается в журнал.

Расширение предлагает один способ оплаты, ведущий на страницу MultiSafepay. У него нет отдельных способов оплаты OpenCart для каждого способа MultiSafepay, нет встроенных полей карты, кнопок экспресс-оплаты Apple Pay или Google Pay, подписок, периодических платежей или сохранённых карт, а также нет подтверждения или отмены холдирования из OpenCart. Данные корзины не передаются, поэтому способы оплаты с отсрочкой, которым они нужны (например, Klarna, in3 или Riverty), для этих заказов MultiSafepay не предлагает.

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

Order statuses

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

Order status after payment (default Processing): MultiSafepay подтвердил платёж (завершён или отправлен) с точной суммой и валютой заказа. Примечание показывает платёж, способ оплаты и среду.

MultiSafepay payment on hold status (default Pending), before payment: платёж не проведён (его проверяет MultiSafepay) или зарезервирован (авторизован). Чтобы получить деньги, подтвердите зарезервированный платёж в MultiSafepay Control. Заказ автоматически переходит в статус Order status after payment, когда MultiSafepay сообщает о его завершении, или в Payment error status, когда платёж отклонён, отменён, истёк или аннулирован.

MultiSafepay payment on hold status, after payment: MultiSafepay подтвердил сумму или валюту, отличающиеся от суммы заказа, тестовый платёж был проведён, пока расширение работает в боевом режиме (реальные деньги не получены), или платёж был завершён после того, как заказу присвоили другой статус, например «отменён». Примечание объясняет это. Проверьте транзакцию в MultiSafepay Control и выполните заказ или сделайте возврат.

MultiSafepay payment on hold status, after a chargeback: MultiSafepay сообщил о чарджбэке по платежу оплаченного заказа: деньги были списаны с вашего счёта.

Payment error status (default Failed): непроведённый или зарезервированный платёж впоследствии был отклонён, отменён, истёк или аннулирован.

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

Оплаченный или возвращённый заказ никогда не открывается заново из-за позднего уведомления. Если для уже оплаченной корзины завершён второй платёж, оплаченный заказ не меняется. Примечание просит вас вернуть дубликат в MultiSafepay Control.

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

Вкладка VibeFox MultiSafepay Gateway

В Sales > Orders откройте заказ, оплаченный через MultiSafepay. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox MultiSafepay Gateway показывает MultiSafepay order (с меткой Test environment для тестовых платежей), Method, Status, суммы Paid / refunded, форму возврата, историю возвратов и MultiSafepay notes заказа. Вкладка показывается пользователям, которые имеют доступ к расширению.

Возвраты

Во вкладке VibeFox MultiSafepay Gateway введите Amount (подставляется сумма, которая ещё не возвращена), при необходимости Reason (optional), и нажмите Refund via MultiSafepay. Подтвердите вопрос Refund this amount through MultiSafepay? This cannot be undone. Поддерживаются полный и частичный возврат. Нужно право изменять расширение (задаётся в System > Users > User Groups). Возвраты выполняются в сумме и валюте, в которых MultiSafepay списал деньги, поэтому после расхождения суммы можно вернуть не больше того, что покупатель фактически заплатил, а не сумму заказа. Возврат отправляется в ту среду, в которой был сделан платёж (тестовую или боевую), поэтому API-ключ этой среды должен быть задан. Если MultiSafepay не принимает возврат, вкладка показывает MultiSafepay refund failed: с ошибкой MultiSafepay, и возврат не регистрируется. Успешный возврат добавляется в историю возвратов и примечания вместе с идентификатором возврата MultiSafepay. Полный возврат переводит заказ в статус Refunded status без уведомления покупателя и без возврата товаров на склад, как и ручная смена статуса. Частичный возврат статус не меняет. Возвраты доступны, когда MultiSafepay сообщил о платеже.

Возвраты товаров в Sales > Returns не возвращают деньги через MultiSafepay.

Возвраты, сделанные в MultiSafepay Control, добавляются в примечания, когда MultiSafepay о них сообщает. Статус заказа автоматически не меняется. При необходимости обновите его вручную.

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

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

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

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

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

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

MultiSafepay does not appear at checkout: проверьте, что лицензия активна, Enable/Disable включено и в текущем режиме есть API-ключ: Test API key в тестовом режиме, Live API key в боевом. Страница настроек показывает предупреждение, если ключа нет. Покупатель должен платить в валюте, которую принимает MultiSafepay (валюта, выбранная в магазине). Также проверьте, что платёжный адрес входит в выбранную Geo Zone, и что сумма заказа достигает значения Total из настроек.

The payment went through, but the order stays without a status: уведомление не дошло до магазина. Проверьте, что магазин доступен из интернета и что задан API-ключ среды платежа, так как расширение получает статус через API MultiSafepay. Если API недоступен или ключ отсутствует, уведомление отвечает ERROR, и MultiSafepay повторяет его. Заказ также получает статус, когда покупатель возвращается в магазин и когда он пытается снова оплатить ту же корзину.

Notification answers Invalid request: в запросе не было корректного ID транзакции. Уведомления от MultiSafepay всегда содержат его.

The customer sees an error after Confirm Order: включите Debug log и посмотрите поле Log на странице расширения. This payment method is not available. означает, что сессия оформления заказа больше не соответствует заказу, либо способ оплаты тем временем выключили: покупателю нужно перезагрузить оформление заказа. This payment method is temporarily unavailable. Please choose another payment method. обычно означает неверный или отсутствующий API-ключ. MultiSafepay cannot accept this order amount or currency. Please choose another payment method. означает, что MultiSafepay не принял сумму или валюту.

The customer comes back and sees Payment verification failed.: адрес возврата не соответствует платежу этого магазина, например из-за старой или изменённой ссылки. Покупатель может оплатить снова через оформление заказа.

Order is in the on hold status: прочитайте примечания во вкладке VibeFox MultiSafepay Gateway. Платёж может быть не проведён или зарезервирован, оплаченные сумма или валюта могли отличаться от заказа, тестовый платёж мог прийти в боевом режиме, платёж мог поступить после отмены заказа, или был чарджбэк. Проверьте транзакцию в MultiSafepay Control.

Test payments do not confirm a live order: тестовый платёж никогда не оплачивает заказ, пока расширение работает в боевом режиме; вместо этого заказ переводится на удержание. Ранее выполненные тестовые платежи по-прежнему проверяются и возвращаются с тестовым ключом после перехода на боевой режим.

No refund form in the tab: вкладка сообщает причину: платёж ещё не передан, он полностью возвращён, или ваша группа пользователей не имеет права изменять расширение.

Refund fails with a message about the environment: платёж был сделан в тестовой или боевой среде, а API-ключ этой среды не задан. Введите его и повторите попытку.

Для разработчиков: расширение вызывает события OpenCart mspg_supported_currencies и mspg_order_request, чтобы изменить список поддерживаемых валют и данные платежа, передаваемые в MultiSafepay.

Удаление

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

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

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