VibeFox Comgate for OpenCart — Помощь

Требования

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

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

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

Валюта: CZK, EUR, PLN, HUF, USD, GBP, RON, HRK, NOK или SEK. Для других валют и для сумм ниже минимума Comgate (например, 1 CZK, 0.10 EUR или 100 HUF) способ оплаты скрывается. Платежи в HUF округляются до целых форинтов, как того требует Comgate.

Аккаунт Comgate: вам нужны Merchant ID и secret (пароль для фоновой связи) подключения вашего магазина в клиентском портале Comgate, а также URL уведомлений, указанный там (см. Настройка). Comgate использует одинаковые Merchant ID и secret для тестовых и боевых платежей.

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

Установка

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

OpenCart 3

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

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

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

4. Введите Merchant ID и Secret из клиентского портала Comgate и укажите там URL уведомлений (см. Настройка).

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

OpenCart 4

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

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

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

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

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

Настройка

Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Comgate Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если Comgate включён, но не заполнены Merchant ID или secret (способ оплаты тогда скрыт при оформлении заказа, пока оба поля не заполнены), а также если валюта магазина по умолчанию не поддерживается Comgate. Пока включён тестовый режим, страница показывает Test mode is on: payments are created as Comgate test payments and no money is charged. Turn it off before going live. Если у вас нет права на изменение расширения, страница показывает настройки, но не может их сохранить.

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

Comgate

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

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

Description: текст, который покупатель видит на шаге Confirm Order над кнопкой подтверждения. По умолчанию: Pay securely via Comgate — cards, bank transfers, wallets and more. В тестовом режиме добавляется TEST MODE: no real money is charged. или показывается отдельно, если описание пустое.

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

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

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

Подключение к Comgate

Возьмите идентификатор магазина (Merchant ID) и пароль (secret) в клиентском портале Comgate, в разделе Integration > shop connection settings (страница содержит ссылку на портал). В том же месте укажите URL for passing the payment result (фоновое уведомление), равный URL из поля Notification URL в этом разделе. На OpenCart 3 он выглядит как https://your-store/index.php?route=extension/payment/wcp_comgate_gateway/notify, на OpenCart 4 как https://your-store/index.php?route=extension/wcp_comgate_gateway/payment/wcp_comgate_gateway.notify. Он формируется из адреса витрины вашей установки OpenCart. Скопируйте URL точно так, как он показан в настройках. Comgate вызывает его после каждого платежа; затем расширение повторно проверяет платёж через API статуса Comgate, и только после этого меняется заказ. URL возврата для покупателя отправляются с каждым платежом. Если портал также требует URL возврата (оплачено, отменено, ожидание), используйте второй URL из этого раздела, который оканчивается на back&id=${id}&refId=${refId} (на OpenCart 4 с wcp_comgate_gateway.back&id=${id}&refId=${refId}).

Merchant ID: идентификатор интернет-магазина Comgate (merchant).

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

Test Mode: создаёт тестовые платежи (деньги не списываются). Comgate использует одинаковые Merchant ID и secret для тестовых и боевых платежей; тестовые платежи помечаются test=true. Возвраты всегда отправляются в том режиме, в котором был совершён исходный платёж. По умолчанию: включено.

Страница оплаты

Payment Methods: способы оплаты Comgate, из которых может выбирать покупатель. Показываются только способы, включённые для вашего магазина в Comgate.

Language: язык страницы оплаты Comgate. Automatic (store language, English as fallback) (по умолчанию) или один из 26 языков.

Заказы

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

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

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

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

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

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

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

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

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

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

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

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

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

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

После оплаты покупатель возвращается в ваш магазин. Заказ отмечается оплаченным только после подтверждения Comgate: расширение считывает платёж через API статуса Comgate и когда приходит фоновое уведомление, и когда покупатель возвращается. Затем заказ получает статус стандартным для OpenCart способом, с обычными письмами о заказе и обновлением остатков, а покупатель видит страницу успешного оформления заказа OpenCart. Если заказ был поставлен на удержание, страница добавляет сообщение Your payment is being reviewed. We will contact you if anything else is needed. На OpenCart 4 браузер не передаёт сеанс магазина, когда Comgate возвращает покупателя, поэтому расширение сначала показывает короткую страницу, которая заново открывает тот же адрес возврата из вашего магазина: покупатель сохраняет корзину и вход в учётную запись.

Если платёж ещё не подтверждён, когда покупатель возвращается (например, банковский перевод в пути), страница Payment confirmation показывает сообщение Comgate has not confirmed your payment yet. Your order will be confirmed automatically as soon as the payment is confirmed — please do not pay again. с кнопкой Check again и кнопкой Back to checkout.

Если платёж отменён или истёк, покупатель возвращается к оформлению заказа с сообщением The Comgate payment was cancelled or has expired. You can try again or choose another payment method. На OpenCart 4 сообщения оформления заказа показываются над страницей оформления заказа. Корзина сохраняется. Каждая новая попытка (OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order, OpenCart 4 оставляет один заказ для оформления и обновляет его) сначала проверяет в Comgate предыдущие попытки этой корзины. Если одна из них уже оплачена, её заказ подтверждается, и покупатель переходит на страницу успеха без повторного списания; открытые попытки отменяются в Comgate. Поздний платёж более ранней попытки по-прежнему распознаётся и подтверждает свой заказ. Корзина, которая уже оплачена другим заказом, повторно не списывается: покупатель переходит на страницу успеха.

На OpenCart 4 заказ остаётся в оформлении заказа до показа страницы успеха. Если этот заказ тем временем был отменён без оплаты, Confirm Order возвращает покупателя к оформлению заказа с сообщением об отменённом платеже. Если он был закрыт иначе (например, возвращён или отменён после оплаты), сообщение: Your previous order is closed (cancelled or refunded). Please confirm the order again: the cart will be paid with a new order. В обоих случаях следующий Confirm Order оплачивает новый заказ корзины. Если заказ уже оплачен, а корзина с тех пор изменилась (другие товары или количество), покупатель возвращается к оформлению заказа, и изменённая корзина получает новый заказ и собственный платёж.

Если Comgate не может начать платёж, покупатель остаётся на шаге Confirm Order с коротким сообщением над кнопкой, например The Comgate payment could not be started. Please try again or choose another payment method., о том, что Comgate не принимает эту сумму или валюту, либо что выбранный способ оплаты Comgate недоступен. Техническая причина записывается в журнал.

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

Расширение принимает только разовые платежи на странице Comgate. Оно не поддерживает регулярные платежи, подписки или сохранённые карты, встроенную форму оплаты Comgate, кнопки Apple Pay или Google Pay на вашем сайте (они доступны на странице Comgate), а также подтверждение или отмену предавторизаций из OpenCart. Без уведомления статус платежа автоматически не опрашивается; он проверяется только при возврате покупателя.

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

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

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

Order Status After Payment (default Processing): Comgate сообщил о платеже как PAID с той же суммой и валютой. Примечание показывает транзакцию Comgate и сумму. Тестовым платежам присваивается примечание Comgate test payment — no money was charged.

Comgate Payment On Hold Status (default Pending): оплаченная сумма или валюта отличаются от заказа, тестовый платёж подтверждён, пока магазин работает в боевом режиме (деньги не получены), либо платёж только авторизован (предавторизация в вашем аккаунте Comgate). Авторизованный платёж становится оплаченным автоматически, когда вы его подтвердите в портале Comgate. Примечание объясняет причину.

Payment Canceled Status (default Canceled): авторизованный платёж был отменён или истёк в Comgate. Если после этого Comgate подтверждает платёж, заказ снова открывается как оплаченный с примечанием проверить остатки перед отправкой.

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

Если Comgate сообщает о ещё одном платеже PAID для заказа, который уже оплачен, заказ не меняется. Примечание просит проверить его в портале Comgate и вернуть дубликат. То же относится к случаю, когда та же корзина оплачивается ещё раз с другим заказом (например, в двух вкладках браузера одновременно): этот заказ не получает статус, а оплаченный заказ получает примечание. Если платёж приходит для заказа, статус которого вы тем временем изменили, статус не трогается, и примечание просит проверить заказ. Повторное подтверждение никогда не открывает заново возвращённый заказ.

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

VibeFox Comgate Gateway tab

В Sales > Orders откройте заказ, оплаченный через Comgate. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Comgate Gateway показывает Comgate transaction (transId) с меткой Test mode для тестовых платежей, Status, Payment amount, Order total / refunded, причину проверки, форму возврата, историю возвратов и Comgate notes заказа. Вкладка показывается пользователям, у которых есть доступ к расширению.

Возвраты

На вкладке VibeFox Comgate Gateway введите Amount (подставляется сумма, которая ещё не возвращена), при необходимости Reason (optional), и нажмите Refund via Comgate. Подтвердите вопрос Refund this amount through Comgate? This cannot be undone. Поддерживаются полные и частичные возвраты. Нужно право на изменение расширения (задаётся в System > Users > User Groups), а Merchant ID и secret должны быть заданы. Возврат направляется на оплаченную транзакцию Comgate и отправляется в том режиме (тестовом или боевом), в котором был совершён исходный платёж. Comgate возвращает только платежи PAID и не больше оплаченной суммы; возвраты в HUF должны быть целым числом форинтов. Если Comgate не принимает возврат, вкладка показывает ошибку, и возврат не фиксируется. Успешный возврат добавляется в историю возвратов и в примечания с суммой, транзакцией Comgate и причиной. Полный возврат устанавливает заказу Refunded Status без уведомления покупателя и без возврата товаров на склад, как при ручной смене статуса. Частичный возврат статус не меняет.

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

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

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

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

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

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

Comgate does not appear at checkout: проверьте, что лицензия активна, Enable / Disable включён, заполнены Merchant ID и Secret, валюта оформления поддерживается, а сумма заказа не ниже минимума Comgate (например, 1 CZK, 0.10 EUR или 100 HUF). Также проверьте, что платёжный адрес входит в выбранную Geo Zone, и что сумма заказа достигает Total, заданного в настройках.

The payment went through, but the order stays without a status: Comgate не доставил фоновое уведомление. Проверьте URL for passing the payment result в портале Comgate (точно совпадающий с Notification URL из настроек), что ваш магазин доступен из интернета, и журнал (включите Debug Log). Comgate повторяет недоставленные уведомления; расширение отвечает ошибкой каждый раз, когда не смогло обработать уведомление, поэтому оно будет отправлено повторно. Заказ также получает статус, когда покупатель возвращается в магазин.

Notification answers Invalid merchant or secret: Merchant ID или secret в настройках не совпадают с подключением магазина в портале Comgate.

Notification answers Gateway not configured: Merchant ID или secret в настройках пусты. Comgate повторит попытку, когда они будут заполнены.

Notification answers Unknown transaction, Order not found or Reference mismatch: уведомление относится к платежу, который этот магазин не создавал для данного заказа. Ничего не меняется.

Notification answers Status verification failed, Status verification rejected or Busy, retry later: API статуса Comgate недоступен, отклонил запрос, либо заказ в тот же момент обрабатывался другим запросом. Busy также является ответом, когда не удалось установить статус заказа; причина указана в журнале. Comgate повторит уведомление.

The notification URL shows code=1&message=POST%20required in the browser: это нормально. URL принимает запросы только от Comgate.

The customer sees We could not verify the Comgate payment: ссылка возврата не совпала с заказом. Если деньги были списаны, уведомление всё равно подтверждает заказ. Проверьте платёж в портале Comgate, прежде чем покупатель заплатит снова.

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

The customer sees The order total is below the minimum amount accepted by Comgate or A valid billing e-mail address is required for Comgate payments: заказ в таком виде нельзя оплатить через Comgate.

Order is in the on-hold status after payment: прочитайте примечания на вкладке VibeFox Comgate Gateway. Оплаченная сумма или валюта отличались, в боевом режиме пришёл тестовый платёж, либо платёж только авторизован. Проверьте платёж в портале Comgate, затем вручную завершите заказ или верните платёж.

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

Refund fails: прочитайте сообщение на вкладке. Comgate rejected the refund: the amount exceeds the refundable amount. означает, что сумма больше остатка к возврату; платёж в статусе, отличном от PAID, вернуть нельзя. Comgate could not be reached. The refund was not made — please try again later. означает проблему соединения.

Для разработчиков: события OpenCart comgate_p_currencies (поддерживаемые валюты и их минимумы) и comgate_p_create_params (параметры платежа Comgate и заказа) позволяют другим расширениям их изменять.

Удаление

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

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

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