VibeFox Comgate for PrestaShop — Помощь

Требования

PrestaShop: 8.0–9.x.

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

HTTPS: ваш магазин должен быть доступен из интернета по HTTPS, чтобы Comgate мог доставить фоновое уведомление.

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

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

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

Установка

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

2. По окончании загрузки нажмите Configure или позже найдите VibeFox Comgate Gateway в списке модулей и нажмите Configure.

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

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

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

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

Настройка

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

Comgate

Enable / Disable: Enable Comgate Payment Gateway включает или выключает способ оплаты. Default: off.

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

Description: текст под способом оплаты на странице оформления заказа. Default: Pay securely via Comgate — cards, bank transfers, wallets and more. В тестовом режиме к нему добавляется TEST MODE: no real money is charged., либо эта фраза выводится отдельно, если описание пустое.

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

Возьмите идентификатор магазина (Merchant ID) и пароль (секрет) в клиентском портале Comgate, раздел Integration > shop connection settings. Там же укажите URL for passing the payment result (фоновое уведомление), равным URL из поля Notification URL в этом разделе. При ЧПУ-адресах он выглядит так: https://your-shop/module/wcp_comgate_gateway/webhook, возможно с кодом языка, например /en/. Копируйте URL точно так, как он показан в настройках. Comgate вызывает его после каждого платежа; модуль затем перепроверяет платёж через API статуса Comgate, прежде чем что-либо изменить. Адреса возврата для покупателя передаются с каждым платежом. Если портал также запрашивает адреса возврата (оплачено, отменено, в ожидании), используйте второй URL из этого раздела, который заканчивается на return?id=${id}&refId=${refId}.

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

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

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

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

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

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

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

Заказы

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

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

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

Debug Log: записывает запросы к API и уведомления в файл logs/comgate_p_debug.log.php в папке модуля. Открыть файл через веб нельзя. Секрет и персональные данные никогда не записываются в журнал. Ошибки записываются всегда. Default: off.

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

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

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

На этапе оплаты покупатель выбирает способ оплаты (по умолчанию Comgate) и подтверждает заказ. Модуль создаёт платёж в Comgate на сумму корзины в валюте корзины и перенаправляет покупателя на страницу оплаты Comgate. Адрес электронной почты и имя покупателя передаются в Comgate, а платёж помечается как Cart с номером корзины. Нужен корректный адрес электронной почты. На странице Comgate покупатель платит одним из разрешённых вами способов. На этом этапе заказа ещё не существует.

После оплаты покупатель возвращается в ваш магазин. Заказ помечается как оплаченный только после подтверждения Comgate: модуль получает данные платежа через API статуса Comgate и когда приходит фоновое уведомление, и когда покупатель возвращается. Затем заказ создаётся, и покупатель видит стандартную страницу подтверждения заказа. Если заказ был переведён в статус ожидания, страница добавляет сообщение Your payment is being reviewed. We will contact you if anything else is needed. Если предавторизованный заказ был отменён позже, страница показывает Your Comgate payment was not completed. Please contact us about this order.

Если на момент возврата покупателя платёж ещё не подтверждён, например банковский перевод в пути, появляется страница Payment confirmation с сообщением Comgate has not confirmed your payment yet. Your order will be created 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. Корзина сохраняется. При каждой новой попытке сначала проверяется предыдущая, поэтому уже прошедший платёж не списывается дважды, а предыдущая попытка отменяется в Comgate, если она ещё открыта. Поздний платёж по более ранней попытке всё равно создаёт заказ.

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

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

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

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

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

Заказа ещё нет: покупателя отправили в Comgate, и он ещё не оплатил, либо Comgate сообщает о платеже как об ожидающем. Существует только корзина.

Payment accepted or Delivered: Comgate сообщил о платеже как о PAID с той же суммой и валютой. Статус соответствует Order Status After Payment. Платёж записывается с идентификатором транзакции Comgate. Тестовые платежи получают примечание Comgate test payment — no money was charged.

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

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

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

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

Блок оплаты Comgate

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

Возвраты

В блоке Comgate payment введите сумму (подставляется сумма, которая ещё не возвращена), при необходимости укажите причину и нажмите Refund via Comgate. Подтвердите вопрос Refund this amount through Comgate? This cannot be undone. Поддерживаются полные и частичные возвраты. Нужно право на редактирование заказов; доступ к страницам модулей не требуется. Возврат отправляется в оплаченную транзакцию Comgate и выполняется в том режиме (тестовом или боевом), в котором прошёл исходный платёж. Comgate возвращает только платежи в статусе PAID и не больше оплаченной суммы; возвраты в HUF должны быть на целое число форинтов. Если Comgate отклонит возврат, блок покажет ошибку, и возврат не будет зарегистрирован. Успешный возврат добавляется в историю возвратов и в примечания с суммой, транзакцией Comgate и причиной. Полный возврат переводит заказ в статус Refunded. Частичный возврат статус не меняет.

Возвраты доступны только для оплаченных заказов. Заказ, находящийся на удержании из-за несовпадения суммы или валюты, нельзя вернуть из PrestaShop; вернуть его нужно в портале Comgate. Модуль не создаёт кредит-ноты. Стандартные кнопки возврата PrestaShop на странице заказа не возвращают деньги через Comgate. Возвраты, оформленные в портале Comgate, в магазин не передаются.

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

Модуль работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Comgate Gateway — это первый блок на странице Modules > Module Manager > VibeFox Comgate Gateway > Configure, над настройками. Введите ключ в поле License key и нажмите Activate. После этого блок показывает ключ в скрытом виде, статус (например, дату, до которой действует лицензия, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: presta-payment-comgate и ссылка Manage licenses and domains in your account, которая открывает ваш аккаунт на vibefox.net. Изменить ключ могут только сотрудники с правом Configure для модуля. Тексты блока соответствуют языку бэк-офиса (включены английский и русский).

Если ключ не принят, блок объясняет причину, например Key not found, This key belongs to another product, Domain limit reached или License expired on с датой. После смены адреса магазина или после освобождения слота домена в вашем аккаунте нажмите Check now. Если сервер лицензий недоступен, модуль продолжает работать по последнему известному статусу.

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

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

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

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

Comgate не появляется при оформлении заказа: проверьте, что лицензия действует, включён Enable / Disable, заполнены Merchant ID и Secret, валюта корзины поддерживается и сумма заказа не ниже минимума Comgate (например 1 CZK, 0,10 EUR или 100 HUF). В разделе Payment > Preferences проверьте, что модулю разрешены валюта корзины, страна покупателя и группа покупателя.

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

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

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

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

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

URL уведомления в браузере показывает code=1&message=POST%20required: это нормально. URL принимает только запросы от Comgate.

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

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

Заказ после оплаты в статусе Comgate payment on hold: прочитайте примечания в блоке Comgate payment. Оплаченные сумма или валюта отличались, тестовый платёж пришёл в боевом режиме, либо платёж только авторизован. Проверьте платёж в портале Comgate и вручную завершите заказ или оформите возврат.

Возврат не проходит: прочитайте сообщение в блоке. 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. означает проблему со связью.

Удаление

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

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