VibeFox Helcim for OpenCart — Помощь
Требования
OpenCart: 3.0.x (проверено на 3.0.5.0) или 4.0.2 и новее (проверено на 4.1.0.3).
PHP: 8.0 или новее.
HTTPS и PCI DSS: данные карты вводятся на странице оформления заказа и передаются с вашего сервера в Helcim. Они никогда не сохраняются и не записываются в журнал, но проходят через ваш сервер, поэтому магазину нужен SSL-сертификат для оформления заказа, а хостинг должен соответствовать PCI DSS (SAQ D).
Валюта: Helcim обрабатывает платежи в CAD и USD. Способ оплаты показывается только тогда, когда валюта оформления заказа входит в число Account currencies, заданных в расширении.
Счёт Helcim: торговый счёт Helcim в Канаде или США и API-токен с правом обработки транзакций (см. Configuration). Тестовый (developer) счёт Helcim для проверки необязателен.
Лицензионный ключ VibeFox: приобретается на vibefox.net. Один ключ работает на одном домене.
Установка
Загрузка — это один zip-архив с пакетами для обеих версий OpenCart. Распакуйте его на своём компьютере. Он содержит README.txt, пакет для OpenCart 3 wcp_helcim_gateway-oc3-(version).ocmod.zip и пакет для OpenCart 4 wcp_helcim_gateway.ocmod.zip. Устанавливайте только пакет для вашей версии OpenCart. Лицензионный ключ одинаков для обеих версий.
OpenCart 3
1. В админ-панели перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_helcim_gateway-oc3-(version).ocmod.zip. У расширения нет модификаций OCMOD, поэтому обновлять Extensions > Modifications не нужно. Вместо установщика можно скопировать содержимое папки upload из этого пакета в корневую папку вашего магазина.
2. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Helcim Gateway и нажмите Install (зелёная кнопка +). Вашему пользователю админки нужно право изменять список платёжных расширений.
3. Нажмите Edit (кнопка с карандашом), чтобы открыть страницу настроек. Вставьте лицензионный ключ VibeFox в поле License key в блоке лицензии вверху страницы и нажмите Activate (см. License key).
4. В Helcim откройте All Tools > Integrations > API Access Configuration, создайте API-доступ с правом обработки транзакций (покупки, предавторизации, списания и возвраты) и скопируйте его токен.
5. Вставьте токен в поле Live API token, а токен вашего тестового счёта Helcim — в поле Test API token, если он у вас есть.
6. Выберите Transaction type и Account currencies, включите Enable / Disable и нажмите Save. Чтобы сначала проверить работу, включите Test mode и оплатите тестовым счётом; затем выключите его.
OpenCart 4
1. В админ-панели перейдите в Extensions > Installer, нажмите Upload и выберите файл wcp_helcim_gateway.ocmod.zip. Не переименовывайте файл: OpenCart 4 берёт код расширения из имени файла, и переименованный пакет не работает.
2. Пакет появляется в списке установленных расширений на той же странице. Рядом с ним нажмите Install (зелёная кнопка +).
3. Перейдите в Extensions > Extensions и выберите тип Payments. Найдите VibeFox Helcim Gateway, нажмите Install (зелёная кнопка +), затем Edit (кнопка с карандашом).
4. Введите лицензионный ключ, API-токены и настройки оплаты, как в шагах 3–6 для OpenCart 3. Страница настроек и её поля одинаковы в обеих версиях.
При новой установке способ оплаты выключен, а тестовый режим отключён.
Настройка
Все настройки находятся на странице расширения: Extensions > Extensions > Payments > VibeFox Helcim Gateway > Edit. Разделы перечислены слева; кнопка Save под списком сохраняет всю страницу. Над настройками страница предупреждает, если валюта магазина по умолчанию не входит в число Account currencies (тогда Helcim предлагается только для заказов в разрешённой валюте), а также, пока способ оплаты включён, если API-токен текущего режима пуст (тогда способ оплаты скрыт на оформлении заказа). Без права изменять расширение страница показывает настройки, но не может их сохранить.
При сохранении поле Title не должно быть пустым (не более 128 символов), Sort Order должно быть целым числом, Total — числом не меньше 0, а каждый статус заказа должен существовать. Если что-то заполнено неверно, ничего не сохраняется, и страница выводит список ошибок.
Helcim
Enable / Disable: Enable Helcim Gateway включает или выключает способ оплаты. По умолчанию: выключено.
Title: название способа оплаты, которое видит покупатель на оформлении заказа. Оно же сохраняется в заказе как название способа оплаты. По умолчанию: Credit card (Helcim). Обязательное поле.
Description: текст, который покупатель видит на шаге Confirm Order над формой карты. По умолчанию: Pay securely with your credit card.
Sort Order: позиция способа оплаты на оформлении заказа. Оставьте поле пустым или введите целое число.
Geo Zone: показывать форму карты только для платёжных адресов из выбранной географической зоны. По умолчанию: All zones. Географические зоны настраиваются в System > Localisation > Geo Zones.
Total: сумма заказа в валюте магазина по умолчанию, которую заказ должен достичь, чтобы способ оплаты был предложен. Оставьте поле пустым, чтобы предлагать его при любой сумме.
Учётные данные API
В Helcim откройте All Tools > Integrations > API Access Configuration, создайте API-доступ и скопируйте его токен. Дайте ему право обработки транзакций для покупок, предавторизаций, списаний и возвратов. Тестовые счета Helcim используют тот же адрес API, что и боевые, поэтому тестовый режим просто использует токен вашего тестового счёта Helcim. Раздел содержит ссылку на документацию API Helcim.
Live API token: API-токен вашего боевого счёта Helcim. Используется, когда тестовый режим выключен.
Test mode: использует Test API token (тестовый счёт Helcim). Платежи, списания и возвраты идут на ваш тестовый счёт Helcim, а покупатели видят уведомление о тестовом режиме. Списания и возвраты заказа всегда используют токен того режима, в котором заказ был оплачен. По умолчанию: выключено.
Test API token: API-токен вашего тестового (developer) счёта Helcim. Используется, когда тестовый режим включён.
Сохранённые токены больше не показываются. Поле остаётся пустым и показывает Saved — leave empty to keep it. Введите новое значение, только если хотите его изменить. Чтобы удалить сохранённый токен, отметьте Clear the saved token on save под полем и нажмите Save.
Оплата
Transaction type: способ списания средств с карты.
Account currencies: валюты, в которых ваш счёт Helcim может принимать платежи. Заказы всегда списываются в валюте заказа. Для других валют способ оплаты на оформлении заказа скрыт.
Заказы
Заказ создаётся на шаге Confirm Order без статуса (отсутствующий заказ) и получает статус только после того, как Helcim одобрит карту. Каждое поле перечисляет статусы заказов вашего OpenCart.
Order Status After Payment: карта списана (покупка или списание предавторизации). По умолчанию: В обработке.
Authorized Status: предавторизация: средства только заблокированы, но ещё не списаны. Списать их можно кнопкой Capture payment на вкладке заказа. По умолчанию: Ожидание, потому что в OpenCart нет статуса On hold.
On Hold (Review) Status: ответ Helcim не совпадает с заказом (частичное одобрение, другая валюта, нет ID транзакции или сумма заказа отличается от суммы списания). Перед выполнением заказа проверьте транзакцию в Helcim; в примечании указано, почему. По умолчанию: Ожидание. Чтобы отличать заказы с предавторизацией от заказов на проверке, вы можете создать собственные статусы в System > Localisation > Order Statuses.
Canceled Status: незавершённая предавторизация снята на вкладке заказа (покупатель не был списан). По умолчанию: Отменён.
Refunded Status: устанавливается после полного возврата платежа на вкладке заказа. По умолчанию: Возвращён.
Дополнительно
Debug log: записывает запросы и ответы API в файл wc_hlg_debug.log.php в папке журналов OpenCart (storage/logs). Файл нельзя открыть из браузера. Номера карт сокращаются до последних 4 цифр. CVC, срок действия, токены, имена, адреса, e-mail и IP-адреса никогда не записываются. Ошибки (отклонённые или неуспешные платежи, ошибки API, неудачные списания и возвраты) записываются всегда, даже когда опция выключена. По умолчанию: выключено.
Log: показывает размер журнала и его последние записи. Нажмите Clear log, чтобы очистить его.
Delete data on uninstall: если включено, при удалении расширения удаляются настройки шлюза и файлы журнала. Транзакции и возвраты Helcim всегда сохраняются, поэтому заказы, оплаченные ранее, можно будет списать и вернуть после повторной установки. По умолчанию: выключено.
Импорт / экспорт
Export: Download JSON сохраняет настройки в файл JSON. API-токены не экспортируются.
Import: вставьте ранее экспортированный JSON и нажмите Import, чтобы восстановить настройки. Сохранённые API-токены остаются.
Оформление заказа
На шаге Payment Method покупатель выбирает способ оплаты (по умолчанию Credit card (Helcim)). На шаге Confirm Order покупатель видит значок карты, ваше описание и форму с полями Card Number, Expiry (MM/YY), CVC и Cardholder Name. В тестовом режиме форма показывает TEST MODE — payments go to a Helcim test account, no real charges are made. OpenCart создаёт заказ на этом шаге, по-прежнему без статуса. Когда покупатель нажимает Confirm Order, расширение проверяет контрольную сумму номера карты, что срок действия корректен и не истёк, что CVC состоит из 3 или 4 цифр и что имя заполнено. Ошибки показываются над формой, и ничего не отправляется в Helcim.
В OpenCart 4 покупатель выбирает способ оплаты кнопкой Choose в блоке способа оплаты, в окне Payment method options. Форма карты затем появляется в блоке подтверждения заказа внизу страницы оформления заказа, над кнопкой Confirm Order. По умолчанию OpenCart 4 не запрашивает платёжный адрес; тогда расширение отправляет в Helcim для проверки адреса адрес доставки вместе с именем владельца карты.
Ваш сервер затем отправляет карту в Helcim как покупку или предавторизацию на сумму заказа в валюте заказа. Имя владельца карты, платёжный адрес, телефон и e-mail передаются для проверки адреса. Платёж в Helcim отображается с номером счёта, который состоит из номера заказа, -OC и короткого кода. Helcim отвечает в том же запросе. Заказ получает статус только после того, как Helcim одобрит транзакцию, стандартным способом OpenCart, с обычными письмами о заказе и обновлением остатков. Корзина сразу очищается, и покупатель попадает на стандартную страницу успешного оформления заказа OpenCart.
Для одной корзины одновременно выполняется только одна попытка оплаты, и оплаченная корзина никогда не списывается повторно, даже если OpenCart в это время создал для неё новый заказ (OpenCart 3 создаёт новый заказ каждый раз, когда показывается шаг Confirm Order; в OpenCart 4 более ранний заказ или вторая вкладка браузера по-прежнему могут удерживать ту же корзину). OpenCart 4 хранит один заказ для оформления и обновляет его, поэтому после отклонённой карты покупатель оплачивает тот же заказ. Если этот заказ тем временем был закрыт (например, вы его отменили) или он уже оплачен, а в корзине теперь новая покупка, Confirm Order возвращает покупателя на страницу оформления заказа с сообщением Your previous order is already closed (cancelled or refunded by the store) or paid for another cart. Please confirm the order again: the cart will be paid with a new order. над ним, а следующее нажатие Confirm Order оплачивает новый заказ корзины. Любое изменение корзины, в том числе новое количество, считается новой корзиной, которой нужна собственная оплата. Каждая попытка использует ключ идемпотентности. Если Helcim не отвечает, заказ остаётся без статуса, а повторная попытка в течение 5 минут возвращает исходный результат Helcim, а не списывает карту дважды. Если платёж одобрен, но статус заказа не удалось установить, следующая попытка для той же корзины установит статус без повторного списания с карты.
Сообщения, которые покупатель может увидеть над формой: Your card was declined. Please check the card details or use another card. при отказе Helcim; Payment failed: с причиной от Helcim для других отклонённых запросов; We could not confirm your payment with the card processor. Please try again in a minute; if the problem persists, contact us before using another card. когда Helcim не отвечает; This payment method is temporarily unavailable. Please choose another payment method. когда API-токен отклонён; Your payment is already being processed. Please wait a moment and check your e-mail before trying again. при повторной отправке формы; Your payment was received, but the order could not be completed automatically. Please contact us — do not pay again. когда платёж одобрен, но статус заказа не удалось установить. Покупатель остаётся на шаге Confirm Order с той же корзиной. Технические подробности записываются в журнал.
Расширение не использует HelcimPay.js или Helcim.js, поэтому данные карты проходят через ваш сервер. В нём нет сохранённых карт, подписок, платежей ACH или банковских переводов, Apple Pay, Google Pay или 3-D Secure, а также вебхуков Helcim.
Заказы и возвраты
Статусы заказов
Без статуса (отсутствующий заказ): карта отклонена, Helcim не ответил или покупатель ещё не оплатил. Отказы и ошибки записываются в журнал и добавляются как примечания. В Sales > Orders такие заказы показываются только с фильтром Order Status, установленным на Missing Orders.
Order Status After Payment (по умолчанию Processing): покупка одобрена или предавторизация списана. В примечании указаны ID транзакции, код одобрения, тип карты, последние 4 цифры и режим.
Authorized Status (по умолчанию Pending): предавторизация одобрена. Средства только заблокированы. Их можно списать или снять блокировку полным возвратом.
On Hold (Review) Status (по умолчанию Pending): Helcim одобрил транзакцию, но сумма, валюта или ID транзакции в его ответе не совпадают с заказом, например после частичного одобрения или если сумма заказа изменилась во время оплаты. В примечании написано Helcim response verification FAILED. Перед выполнением заказа проверьте транзакцию в Helcim.
Refunded Status (по умолчанию Refunded): платёж полностью возвращён через расширение.
Canceled Status (по умолчанию Canceled): незавершённая предавторизация снята. Покупатель не был списан.
Примечания — это записи в History заказа, которые покупатель не видит.
Вкладка VibeFox Helcim Gateway
В Sales > Orders откройте заказ, оплаченный через Helcim. Внизу страницы заказа, рядом с History и Additional, вкладка VibeFox Helcim Gateway показывает Transaction ID (и ID предавторизации после списания) с меткой Test mode для тестовых платежей, Transaction type и состояние списания, Invoice, Card и код одобрения, суммы Approved / order / refunded, кнопку списания и форму возврата, историю возвратов и Helcim notes заказа. Вкладка показывается пользователям, у которых есть доступ к расширению; списания и возвраты требуют права изменять расширение (настраивается в System > Users > User Groups).
Списание
Для незавершённой предавторизации нажмите Capture payment на вкладке (на кнопке показана сумма) и подтвердите Capture the pre-authorized amount through Helcim? Списывается текущая сумма заказа за вычетом возвратов. Она может быть меньше предавторизованной суммы, но не больше. Списание использует токен режима, в котором был оплачен заказ. После успешного списания заказ получает статус Order Status After Payment. Если списание не удалось, вкладка показывает причину и добавляет её в примечания.
Возвраты
На вкладке введите Amount (подставляется сумма, которая ещё не возвращена), при желании Reason (optional) и нажмите Refund via Helcim. Подтвердите Refund this amount through Helcim? This cannot be undone. Поддерживаются полные и частичные возвраты покупки или списанной предавторизации, но не больше суммы, которую Helcim фактически списал; поэтому после частичного одобрения нельзя вернуть больше, чем заплатил покупатель. Для незавершённой предавторизации кнопка называется Release pre-authorization: снять можно только полную сумму, блокировка удаляется, а заказ получает статус Canceled Status.
Возврат отправляется в режиме, в котором был оплачен заказ, поэтому токен этого режима должен быть задан. Возврат засчитывается только при одобрении Helcim. Если Helcim его отклоняет, вкладка показывает ошибку и возврат не регистрируется. Успешный возврат добавляется в историю возвратов и примечания с ID транзакции возврата Helcim. Полный возврат устанавливает заказу статус Refunded Status без уведомления покупателя и без возврата товаров на склад, как при ручной смене статуса. Частичный возврат статус не меняет. Повтор после тайм-аута не возвращает деньги дважды.
Возвраты товаров в Sales > Returns не возвращают деньги через Helcim. Расширение не получает вебхуки Helcim: списания, возвраты и аннуляции, сделанные в панели Helcim, не отображаются в OpenCart, поэтому выполняйте их со страницы заказа.
Лицензионный ключ
Расширение работает с лицензионным ключом VibeFox с vibefox.net. Блок лицензии License — VibeFox Helcim Gateway — первый блок на странице Extensions > Extensions > Payments > VibeFox Helcim Gateway > Edit, над настройками. Вставьте ключ в поле License key и нажмите Activate. После этого блок показывает ключ в замаскированном виде, статус (например, дату, до которой лицензия действует, и ваш домен) и кнопки Check now для повторной проверки статуса, Change key для ввода другого ключа и Remove key для удаления ключа из этого магазина. Ниже находятся строка Product: opencart-payment-helcim и ссылка 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 с датой. После смены адреса магазина или после освобождения слота домена в вашем аккаунте на vibefox.net нажмите Check now. Если сервер лицензий недоступен, расширение продолжает работать с последним известным статусом.
Один ключ работает на одном домене: адрес магазина из настроек OpenCart. Удаление ключа из магазина не освобождает слот домена. Освободите слот в своём аккаунте на vibefox.net.
Без действующего ключа Helcim не показывается покупателям на оформлении заказа. Если платёж всё же начат, покупатель видит This payment method is not available. Please choose another one. Администратор, вошедший в админку в том же браузере, всё ещё видит способ оплаты в магазине, отмеченный (unlicensed — visible to admins only), чтобы вы могли настроить и проверить расширение до покупки ключа. В OpenCart 4 этот предпросмотр недоступен: магазин не видит вход администратора, поэтому без действующего ключа способ оплаты скрыт для всех. После того как вы один раз откроете страницу Edit, на Dashboard админки появится напоминание. Закройте его кнопкой ×, чтобы скрыть на 7 дней. Существующие заказы не затрагиваются: уже выполненные платежи сохраняются, а списания и возвраты работают.
Когда срок лицензии истекает, расширение продолжает работать, но для обновлений и поддержки нужно продление. Статус проверяется снова автоматически при открытии Dashboard или страницы Edit админки: раз в день в первые 14 дней после ввода ключа, затем раз в неделю. Cron-задание не требуется. Удаление расширения всегда удаляет лицензионный ключ и статус лицензии.
Устранение неполадок
Helcim не появляется на оформлении заказа: проверьте, что лицензия активна, Enable / Disable включено, для текущего режима задан API-токен (Live API token или в тестовом режиме Test API token) и валюта оформления заказа входит в Account currencies. Страница настроек показывает предупреждение, если токен не задан или валюта магазина не разрешена. Также проверьте, что платёжный адрес входит в выбранную Geo Zone, а сумма заказа достигает Total, заданного в настройках.
Покупатель видел сообщение We could not confirm your payment: Helcim не ответил, поэтому карта могла быть списана. Примечание к заказу и журнал указывают счёт Helcim. Проверьте этот счёт в Helcim, прежде чем снова списывать деньги с покупателя. Повторная попытка в течение 5 минут возвращает исходный результат и не списывает дважды.
Покупатели видят This payment method is temporarily unavailable: Helcim отклонил API-токен. Примечание к заказу советует проверить токен и его права. Убедитесь, что у API-доступа есть право обработки транзакций.
Покупатели видят This payment method is not available. Please reload the checkout page.: сессия оформления заказа больше не соответствует заказу, способ оплаты тем временем выключили, или токен либо валюта больше не подходят. Покупатель перезагружает страницу оформления заказа.
Оплата не прошла с причиной Helcim: Helcim отклонил запрос, например из-за карты или платёжных данных. Подробности есть в примечании к заказу и в журнале.
Покупатель видел сообщение Your payment was received, but the order could not be completed: Helcim одобрил платёж, но OpenCart не смог установить статус заказа. Причина есть в журнале. Когда покупатель повторно отправляет ту же корзину, статус устанавливается по уже одобренному платежу без второго списания.
Заказ в статусе проверки: прочитайте примечания на вкладке VibeFox Helcim Gateway. Ответ Helcim не совпал с заказом (проверка ответа не пройдена). Проверьте транзакцию в Helcim, затем выполните заказ или верните платёж.
Списание невозможно: сумма списания должна быть больше 0 и не выше предавторизованной суммы, а токен режима, в котором был оплачен заказ, должен быть задан.
Возврат не удаётся: прочитайте сообщение. Незавершённую предавторизацию можно снять только полностью. Сообщение о режиме означает, что токен режима, в котором был оплачен заказ, пуст. Отклонённый возврат не регистрируется. You do not have permission to capture or refund (modify this extension). означает, что ваша группа пользователей не имеет права изменять расширение.
Тестовые платежи: тестовый режим отправляет платежи, списания и возвраты на ваш тестовый счёт Helcim. Заказы сохраняют режим, в котором были оплачены, поэтому смена режима позже не переносит их списания и возвраты на другой счёт.
Удаление
Перейдите в Extensions > Extensions, выберите тип Payments и нажмите Uninstall (красная кнопка −) рядом с VibeFox Helcim Gateway. Лицензионный ключ и статус лицензии этого расширения всегда удаляются. OpenCart всегда удаляет собственные настройки расширения: Enable / Disable, Sort Order, Geo Zone, Total и статусы заказов из раздела Orders, которые при повторной установке вернутся к значениям по умолчанию. В OpenCart 4 также удаляется событие OpenCart расширения, которое выводит сообщение над страницей оформления заказа. Если включён Delete data on uninstall, удаляются остальные настройки шлюза (название, описание, API-токены, тестовый режим, тип транзакции, валюты счёта, переключатель журнала отладки) и журнал. Если он выключен, они сохраняются для повторной установки. Транзакции и возвраты Helcim всегда сохраняются, поэтому заказы, оплаченные ранее, можно будет списать и вернуть после повторной установки. Существующие заказы сохраняют примечания об оплате.
В OpenCart 4, чтобы удалить также файлы расширения, перейдите в Extensions > Installer после удаления и нажмите Uninstall (оранжевая кнопка −) рядом с VibeFox Helcim Gateway в списке установленных расширений, затем Delete (красная кнопка с корзиной), чтобы удалить загруженный пакет.
Helcim является товарным знаком его правообладателя. Это расширение не аффилировано с Helcim и не одобрено им.